# GridOS

## Docs

- [Connect your AI provider API keys to GridOS](https://gridos.mintlify.app/api-keys.md): Add API keys for Google Gemini, Anthropic Claude, Groq, or OpenRouter to GridOS using the in-app settings panel or a .env file to unlock the model picker.
- [POST /agent/apply — commit a previewed agent write](https://gridos.mintlify.app/api/agent-apply.md): Commit a previewed agent write to the sheet. Pass the values and target_cell from the chat response through to this endpoint to apply the changes.
- [POST /agent/chat/chain — run the agent in a loop](https://gridos.mintlify.app/api/agent-chain.md): Run the GridOS agent in an autonomous loop that applies writes and observes formula results between steps, up to a configurable maximum iteration count.
- [POST /agent/chat — send a prompt to the AI agent](https://gridos.mintlify.app/api/agent-chat.md): Send a natural-language prompt to the GridOS AI agent. Returns a preview of proposed cell writes for you to review before committing them.
- [Authentication — JWT or long-lived API keys](https://gridos.mintlify.app/api/authentication.md): GridOS accepts two credential types: short-lived Supabase JWTs (browser sign-in) and long-lived API keys (gridos_live_sk_) for external AI agents. Both go in the standard Authorization: Bearer header.
- [Create and manage chart overlays via the API](https://gridos.mintlify.app/api/charts.md): List, create, update, and delete chart overlays on any GridOS sheet using the /system/charts endpoints. Supports bar, line, and pie chart types.
- [Developer plugins — upload, test, delete](https://gridos.mintlify.app/api/dev-plugins.md): Hot-upload, test, and delete GridOS plugins without a repo push or server restart. OSS-only, gated behind an explicit env flag because it's a full RCE surface.
- [Engine API — call GridOS as a deterministic compute layer](https://gridos.mintlify.app/api/engine-overview.md): /eval, /schema, and /peek give external AI agents direct access to the GridOS AST kernel without going through the chat agent or UI. Use them to verify spreadsheet math, scout workbook structure, and fetch cell ranges in tens to hundreds of tokens.
- [POST /eval — dry-run formulas without committing](https://gridos.mintlify.app/api/eval.md): Evaluate a list of {cell, formula} pairs against the current workbook state. No writes, no LLM, no preview token. Returns Excel-style results or error sentinels per cell.
- [Write cells and ranges directly to the grid](https://gridos.mintlify.app/api/grid-cell.md): Use POST /grid/cell and POST /grid/range to write individual cells or rectangular blocks of data to any sheet in your GridOS workbook.
- [GET /peek — dense partial-grid fetch](https://gridos.mintlify.app/api/peek.md): Fetch a rectangular cell range as CSV, TSV, or JSON. Designed for AI agents that want concrete cell values from a specific block of the grid without paying the token cost of fetching the full workbook.
- [Plugin secrets — per-user connector credentials](https://gridos.mintlify.app/api/plugin-secrets.md): Store Shopify / Stripe / GitHub / etc. credentials per-user instead of server-global. Values are write-only from the browser; GET only reports which slots are set, never the value.
- [Save, load, export, and import workbooks](https://gridos.mintlify.app/api/save-load-export.md): Persist your GridOS workbook to disk, reload it after a restart, download a portable .gridos file, import a saved workbook, or wipe unlocked cells.
- [GET /schema — token-cheap workbook recon](https://gridos.mintlify.app/api/schema.md): Returns every sheet's bounds, inferred column headers, and dominant data type per column. Designed to give external AI agents a structural overview in roughly 200 tokens instead of 30,000.
- [Manage provider API keys and model availability](https://gridos.mintlify.app/api/settings-providers.md): Configure API keys for Gemini, Anthropic, Groq, and OpenRouter, remove them, and list which models are available given your current configuration.
- [Workbook collaborators — invite, list, revoke](https://gridos.mintlify.app/api/workbook-collaborators.md): Manage who has access to a shared workbook. Owner-only endpoints for invites (registered + pending), a list endpoint that returns both, and a separate revoke path for each.
- [Manage workbooks and sheets via the REST API](https://gridos.mintlify.app/api/workbook-sheets.md): Retrieve workbook metadata, create and rename sheets, switch the active sheet, and rename the workbook itself using these five REST endpoints.
- [GridOS architecture: kernel, providers, agents, frontend](https://gridos.mintlify.app/concepts/architecture.md): How the GridOS pieces fit together — the deterministic Python kernel, the provider abstraction, the agent dispatch, and the FastAPI/vanilla-JS frontend.
- [How GridOS agents read and edit your sheet](https://gridos.mintlify.app/concepts/chat-and-agents.md): Understand GridOS's two built-in AI agents, how automatic routing works, what agents can do, and the hard limits that keep your data safe.
- [GridOS formulas: built-in functions, Excel-ism tolerance, syntax](https://gridos.mintlify.app/concepts/formulas.md): Complete reference for GridOS formula syntax: all 21 built-in primitives, range notation, Excel-ism support, error codes, and the rules for writing formulas in cells.
- [The GridOS plugin system: custom formulas, agents, and models](https://gridos.mintlify.app/concepts/plugins.md): Extend GridOS without forking. Plugins auto-load at boot and can register new primitives, specialist agents, and provider models through three clean seams.
- [Preview and apply: review AI edits before they land](https://gridos.mintlify.app/concepts/preview-apply.md): See how GridOS lets you inspect every AI-proposed cell write before it commits, with automatic collision handling, formula guards, and a permanent audit trail.
- [Realtime collab: live cell sync and presence cursors](https://gridos.mintlify.app/concepts/realtime.md): GridOS broadcasts cell writes and selection changes over Supabase Realtime so collaborators see each other's edits and cursor positions without refreshing.
- [Shared workbooks: invite collaborators to edit the same sheet](https://gridos.mintlify.app/concepts/shared-workbooks.md): GridOS workbooks are single-owner by default; SaaS mode lets the owner invite other accounts as collaborators who edit alongside them with live cell sync and presence cursors.
- [Workbooks, sheets, and cells in GridOS](https://gridos.mintlify.app/concepts/workbook.md): Learn how GridOS organizes your data into workbooks, named sheets, and individually addressable cells — and how persistence keeps your work safe.
- [Lock cells to protect data from AI edits](https://gridos.mintlify.app/configuration/cell-locking.md): Mark individual cells or ranges as read-only in GridOS so the AI agent cannot overwrite them. Lock headers, verified formulas, and reference data.
- [Developer plugin portal: upload and test plugins from the UI](https://gridos.mintlify.app/configuration/developer-plugin-portal.md): An in-UI access point for building GridOS plugins without pushing to the repo. Upload a plugin.py, test its formulas in isolation, delete when you're done. OSS-only and gated behind an explicit env flag because it's a full remote-code-execution surface.
- [Configure LLM providers in GridOS settings](https://gridos.mintlify.app/configuration/llm-providers.md): Connect Google Gemini, Anthropic Claude, Groq, or OpenRouter to GridOS. Real free-tier limits, which provider to start with, and how BYOK storage works.
- [Supported AI models and providers in GridOS](https://gridos.mintlify.app/configuration/supported-models.md): Every AI model available in GridOS with its real free-tier TPM, which are safe for multi-intent builds, and how to add your own.
- [Build financial models with AI in GridOS](https://gridos.mintlify.app/guides/building-financial-models.md): Learn how to build DCF, budget, and revenue models in GridOS by chatting with the AI finance agent — no formulas to write by hand.
- [Chain mode: let the AI build your workbook end-to-end](https://gridos.mintlify.app/guides/chain-mode.md): Chain mode auto-applies every AI step, observes formula results, and continues building until your entire workbook plan is complete.
- [Create and update charts in GridOS with AI](https://gridos.mintlify.app/guides/charts.md): Ask GridOS to generate bar, line, or pie charts from your grid data — and update them in place by describing the change you want.
- [Connectors: Shopify, Stripe, GitHub](https://gridos.mintlify.app/guides/connectors.md): Three shipped BYOK connector plugins turn spreadsheet cells into live dashboards against Shopify, Stripe, and GitHub. Auth per-user via the marketplace Configure modal, or via env vars in OSS mode.
- [Define custom formulas with GridOS macros](https://gridos.mintlify.app/guides/macros.md): Create reusable named formulas in GridOS by asking the AI to propose a macro — then approve it and call it from any cell in your workbook.
- [Plugin marketplace: install, search, and configure plugins](https://gridos.mintlify.app/guides/marketplace.md): The in-app Plugin marketplace lets you toggle which plugins are enabled, configure per-user API keys, and filter a growing catalog by name, category, or install status.
- [Self-evolving formulas: let the agent build new plugins on demand](https://gridos.mintlify.app/guides/self-evolving-formulas.md): When a user asks for a formula that doesn't yet exist, the AI agent can emit a full plugin spec — slug, Python source, and example usage — and you install it with one click. The formula becomes a first-class primitive immediately.
- [Use and save workbook templates in GridOS](https://gridos.mintlify.app/guides/templates.md): Open a built-in GridOS template to start from a structured workbook, or save your own model as a reusable template for future sessions.
- [GridOS: Chat-first spreadsheet powered by your AI key](https://gridos.mintlify.app/introduction.md): GridOS is an agentic spreadsheet for building and editing workbooks by chatting with AI. Bring your own key from Gemini, Claude, Groq, or OpenRouter.
- [Get GridOS running locally and build your first workbook](https://gridos.mintlify.app/quickstart.md): 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 error reference: keys, guards, rate limits, parse failures](https://gridos.mintlify.app/troubleshooting/common-errors.md): Every error message GridOS can surface — what it means, what caused it, and exactly what to do. Covers 400, 401, 413 TPM, 422 formula guard, and parse errors.
- [Troubleshoot AI model output problems in GridOS](https://gridos.mintlify.app/troubleshooting/model-output-issues.md): Fix GridOS model output problems: non-JSON responses, token cap hits, flaky providers, column alignment bugs, #DIV/0! guard triggers, and empty model pickers.
- [Plugin formula not working](https://gridos.mintlify.app/troubleshooting/plugin-issues.md): A guide to the sentinel strings GridOS returns when a plugin formula fails — missing credentials, rate limits, install gate, and more.
- [Realtime sync and shared workbooks](https://gridos.mintlify.app/troubleshooting/realtime-and-sharing.md): Diagnosing stuck cursors, missed cell updates, failed invites, and the 'Could not load marketplace' cold-start error.