Get GridOS running locally and build your first workbook

Clone GridOS, install dependencies, start the server, add an API key, and use the hero prompt to build your first AI-powered workbook in minutes.

GridOS runs as a local FastAPI server that you open in your browser. This guide walks you through cloning the repository, installing dependencies, starting the server, and using the landing-page hero prompt to create your first AI-built workbook. You need Python 3.10 or later and at least one LLM API key — Gemini Flash Lite is free, has generous TPM limits, and requires only a Google account, making it the fastest reliable way to get started.

Prerequisites

• Python 3.10+ — check with python --version or python3 --version
• One LLM API key — Gemini Flash Lite is recommended (free, ~250K TPM): aistudio.google.com/app/apikey

You only need one key. GridOS unlocks all models for whichever providers you have configured — you can add more later from the in-app settings panel. See Which provider should I start with? for the full comparison.

Setup

1. Clone the repository

   Clone the GridOS repo and enter the project directory.

   git clone https://github.com/shreydevkar/gridos.git
   cd gridos
   
2. Create and activate a virtual environment

   Using a virtual environment keeps GridOS dependencies isolated from your system Python.

   python -m venv .venv
   source .venv/bin/activate
   

   On Windows PowerShell, activate with:

   .venv\Scripts\Activate.ps1
   
3. Install dependencies

   Install all required packages from requirements.txt. This pulls in FastAPI, Uvicorn, the provider SDKs, and Pydantic.

   pip install -r requirements.txt
   

   The install takes about 30–60 seconds on a typical connection. The key packages are:

   Package	Purpose
   fastapi	REST API framework
   uvicorn	ASGI server
   google-genai	Gemini provider SDK
   anthropic	Claude provider SDK
   openai	Shared SDK for Groq and OpenRouter
   python-dotenv	.env file support

4. Start the server

   Run the Uvicorn server with hot-reload enabled so changes take effect without a restart.

   uvicorn main:app --reload
   

   You should see output like:

   INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
   INFO:     Started reloader process
   

   Open http://127.0.0.1:8000 in your browser. You will land on the GridOS landing page.

   The model picker in the chat composer will be empty until you add at least one API key. Attempting to submit a prompt without a key returns a 400 error: “No LLM provider is configured.”

5. Add an API key

   Click the gear icon in the top menubar to open the Settings panel. Paste your API key into the field for the provider you are using (for example, Groq), then click Save.

   GridOS writes the key to data/api_keys.json, which is gitignored. The model picker in the chat composer immediately lists every model whose provider now has a valid key.

   If you prefer to use a .env file instead of the settings UI, see Connect your API keys for the full list of environment variable names and when each approach is preferable.

6. Build your first workbook

   You are now on the GridOS landing page with a hero prompt field in the center. Type a description of the workbook you want to build and press Enter.

   Some examples to try:

   Build a 4-quarter revenue forecast with 10% QoQ growth
   

   Create a monthly budget tracker with income, fixed costs, and variable expenses
   

   Build a break-even analysis for a product with $50 variable cost and $10,000 fixed overhead
   

   GridOS clears the kernel, routes you to the workbook view, and auto-submits the prompt. The AI agent begins writing cells immediately. You will see preview cards appear in the chat thread as the agent proposes each batch of writes.

7. Review and apply AI suggestions

   Each agent turn produces a preview card in the chat thread showing the proposed cell writes. You have three options:

   • Apply — commits the writes to the sheet. The card badge changes to APPLIED.
   • Dismiss — discards the suggestion. The card badge changes to DISMISSED.
   • Continue chatting — refine the prompt and the agent produces a new suggestion. Previous cards are marked SUPERSEDED.

   GridOS runs a pre-apply formula guard before committing any write. If a proposed formula references an empty cell that would cause a #DIV/0! or similar error, the write is blocked and you see a clear error message — the sheet is never modified.

What to try next

Switch models mid-session

Use the model picker dropdown in the chat composer to switch between providers and models for any individual prompt.

Lock cells

Click any cell and mark it read-only. The AI cannot overwrite locked ranges, even in chain mode.

Open a template

Click File → Templates to browse built-in starters like Simple DCF, Loan Amortization, and Income Statement.

Enable chain mode

Toggle chain mode in the chat composer to let the agent auto-apply steps and keep going until the full plan is done.