> ## Documentation Index > Fetch the complete documentation index at: https://docs.heygaia.io/llms.txt > Use this file to discover all available pages before exploring further. # AI models and tools > Pick your AI provider, change it later, and see which tools work without a key. GAIA needs one AI provider. Everything else here is optional: most tools work with no key. ## Where you change things Any of these saves to the same place, so use whichever is handy. Changes apply right away, with no restart. | Where | Use it for | | - | - | | Setup page at `http://localhost:3000/setup` | First boot | | **Settings → Providers & Tools** | Any time later. Shows **Working**, **Not set up** or **Not available here** for each feature | | `gaia up --llm-provider ...` | The terminal, to skip the AI step in the browser | AI keys are tested before saving. Tool keys are saved as typed. A key saved in Settings beats the same variable in `apps/api/.env`. ## AI models Pick one to start. If you add several, GAIA uses the first available in this order and falls back to the next on failure: OpenRouter, Gemini, OpenAI, Ollama, custom. | Provider | What you need | Environment variable | Notes | | - | - | - | - | | **OpenRouter** | A key from [openrouter.ai/keys](https://openrouter.ai/keys) | `OPENROUTER_API_KEY` | One key for most models. Easiest start | | **Google Gemini** | A key from [aistudio.google.com/apikey](https://aistudio.google.com/apikey) | `GOOGLE_API_KEY` | Has a free tier | | **OpenAI** | A key from [platform.openai.com/api-keys](https://platform.openai.com/api-keys) | `OPENAI_API_KEY` | Also transcribes voice notes | | **Ollama** | Ollama on your machine, no key | `OLLAMA_BASE_URL` | See [Using Ollama](#using-ollama) | | **Custom** | A key, the server's address and a model name | Set in the setup page, Settings or `gaia up` | Any OpenAI-style API. OpenCode and Nous Research are one click | Only OpenRouter, Gemini and OpenAI can read images. ### From the terminal ```bash theme={null} gaia up --llm-provider openrouter --llm-key sk-or-... gaia up --llm-provider ollama --llm-model qwen3 gaia up --llm-provider custom --llm-key sk-... --llm-base-url https://gateway.example.com/v1 --llm-model some-model ``` Run it again with another provider to add or replace one. Custom needs a key, address and model. Ollama needs none of those. If the key is rejected, nothing is saved. Flags are in the [`gaia up` reference](https://docs.heygaia.io/self-hosting/cli-reference#gaia-up). ### Using Ollama GAIA runs in a container, so `localhost` is not your machine. Use `http://host.docker.internal:11434`, which the setup page fills in for you. Then pick a model from the list. > [!TIP] > > On Linux, Ollama only listens on `127.0.0.1`, which the container can't reach. Start it with `OLLAMA_HOST=0.0.0.0 ollama serve`. ## Tools | Tool | Without a key | What a key adds | Environment variable | | - | - | - | - | | Web search | DuckDuckGo, free | Tavily, Exa or Brave for better results, or your own SearXNG server | `TAVILY_API_KEY`, `EXA_API_KEY`, `BRAVE_API_KEY`, `SEARXNG_BASE_URL` | | Reading web pages | The built-in reader, a headless browser on your server | Firecrawl, which gets past sites that block bots | `FIRECRAWL_API_KEY` | | Running code | Off, until you turn on the local sandbox | E2B, a cloud sandbox | `E2B_API_KEY` | | File storage | Your server's disk | Cloudinary | `CLOUDINARY_CLOUD_NAME`, `CLOUDINARY_API_KEY`, `CLOUDINARY_API_SECRET` | | Email | Off | Resend, for notifications and reminders by email | `RESEND_API_KEY` | | Weather | Off | OpenWeather | `OPENWEATHER_API_KEY` | | Scanned documents | Text PDFs and Office files, read on your server | LlamaParse, which reads scanned pages and photos of text | `LLAMA_INDEX_KEY` | | Skill installs | 60 GitHub lookups an hour | A GitHub token, for 5000 an hour | `GITHUB_TOKEN` | | Integrations | Off | Composio, for Gmail, Calendar, Slack and 200+ apps | `COMPOSIO_KEY` | ### Web search Search works on a fresh install through DuckDuckGo. Add a key for better results. GAIA tries providers in this order and moves on when one fails: Exa, Tavily, Brave, your SearXNG, then DuckDuckGo. Exa, Tavily and Brave stop at their free monthly allowance (20,000, 1,000 and 1,000 searches), so search never bills you. SearXNG needs your server's address, no key. ### Running code Coding tools need a sandbox, and neither is on until you choose: | Option | How to turn it on | Cost | | - | - | - | | **E2B** (recommended) | Save an E2B key in **Settings → Providers & Tools**, or set `E2B_API_KEY` | An [E2B](https://e2b.dev) account. Code never runs on your server | | **Local sandbox** | `gaia up --code-sandbox` | Gives GAIA root access to your server | With neither, coding tools say code execution is off. Everything else works. If both are set, E2B is used. > [!WARNING] > > The local sandbox needs your server's Docker socket, which is the same as root. If someone breaks into the API, they control the machine. Use it only on a machine that runs nothing else you care about. Turn it off with `gaia up --no-code-sandbox`. > **How the local sandbox works** > > Each user's code runs in its own `gaia-sandbox-*` container. `--code-sandbox` adds the `docker-compose.sandbox.yml` override, and the CLI remembers it for `gaia start` and `gaia update`. Without the CLI, run `docker compose -f docker-compose.selfhost.yml -f docker-compose.sandbox.yml up -d`. > > Each sandbox sees only its user's files, at `/workspace`. It needs **Docker Engine 26 or newer**; `gaia start` refuses an older one. Limits: > > | Limit | Value | > | - | - | > | Memory | 2 GB, no swap | > | Processes | 512 | > | CPU | 2 cores | > | Privileges | All Linux capabilities dropped, no privilege escalation | > | Network | Internet for `pip` and `npm`, but no route to GAIA's databases or other sandboxes | > | Command time | 5 minutes by default, 30 at most | > > The sandbox can still reach ports your server publishes to all interfaces, like any internet client. > > The first sandbox builds the `gaia-local-sandbox` image on your server, which takes about a minute. It has `curl`, `git` and `sqlite3`, so GAIA can run Claude Code and OpenCode in it (set `ENABLE_AGENT_LAB=true` in `apps/api/.env`). Those runs report back to GAIA through the port the proxy publishes (`WEB_HOST_PORT`). > **Upgrading from a version with one shared sandbox volume** > > Older versions gave every user one shared `gaia-sandbox-workspace` volume. The first `gaia start`, `gaia up` or `gaia update` after upgrading replaces those containers and copies each conversation's files into its owner's workspace. Files with no provable owner stay in the old volume and are listed in the command output and in `_migrations/legacy-sandbox-workspace.json` on the workspace volume. Nothing is deleted: once you have checked the list, remove the old volume with `docker volume rm gaia-sandbox-workspace`. ### File storage Files stay on two Docker volumes on your server. No storage account is needed. | Volume | Holds | | - | - | | `gaia-selfhost_files` | Chat attachments, generated images, profile pictures, support attachments | | `gaia-selfhost_workspace` | Each user's workspace: uploads the agent opens, artifacts, installed skills | Only the file's owner can open it (profile pictures are visible to every member). Set `BLOB_STORE` in `apps/api/.env` to change where files live: | `BLOB_STORE` | Files live in | Use it when | | - | - | - | | `local` (default) | The `gaia-selfhost_files` volume | The API and worker share one machine: `gaia up`, a VPS, Coolify | | `s3` | A bucket on any S3-compatible service | The platform gives a disk to one service only, as on Render and Railway | | `cloudinary` | Your Cloudinary account | As for `s3`, if you already use Cloudinary | For Cloudinary, add the cloud name, API key and API secret in **Settings → Providers & Tools**. Cloudinary links are public to anyone who has them. #### Using an S3 bucket AWS S3, Cloudflare R2, Backblaze B2, MinIO and Railway buckets all work. Files stay private: the bucket is never made public, and GAIA serves each file to signed-in users the same way it serves files from the volume. Set these in `apps/api/.env`, or on both the API and the worker service: ```bash theme={null} BLOB_STORE=s3 S3_ENDPOINT_URL=https://.r2.cloudflarestorage.com S3_BUCKET=gaia-files S3_ACCESS_KEY_ID=... S3_SECRET_ACCESS_KEY=... S3_REGION=auto ``` The key needs permission to read, write and delete objects. For MinIO, also set `S3_ADDRESSING_STYLE=path`. On Railway, add a bucket to the project, then reference its variables from the API and worker services: | Set | To | | - | - | | `S3_ENDPOINT_URL` | `${{Bucket.ENDPOINT}}` | | `S3_BUCKET` | `${{Bucket.BUCKET}}` | | `S3_ACCESS_KEY_ID` | `${{Bucket.ACCESS_KEY_ID}}` | | `S3_SECRET_ACCESS_KEY` | `${{Bucket.SECRET_ACCESS_KEY}}` | | `S3_REGION` | `${{Bucket.REGION}}` | Replace `Bucket` with your bucket's name in Railway. If the bucket's **Credentials** tab says to use path-style URLs, also set `S3_ADDRESSING_STYLE=path`. Moving from the volume to a bucket does not copy the files that are already stored. > **Details** > > With `local`, the API and worker refuse to start if the files volume isn't mounted and writable. With `s3`, they write and delete a test object at startup and refuse to start if the bucket is missing, the keys are wrong or the endpoint can't be reached. Either way, the error names the fix. The `R2_*` and `JUICEFS_META_URL_TEMPLATE` settings belong to GAIA Cloud and are ignored here. ### Integrations Apps like Gmail and Calendar connect through your own Composio project. See [Connect integrations](https://docs.heygaia.io/self-hosting/composio-integrations.md). [MCP servers](https://docs.heygaia.io/self-hosting/mcp-servers.md) need no key. ## Not available on self-host These show as **Unavailable** in Settings, whatever keys you save: * **Voice** needs a LiveKit server and GAIA's voice worker. * **Browser automation** needs GAIA's browser hosts. Reading web pages still works. Other differences: [Self-host vs Cloud](https://docs.heygaia.io/self-hosting/overview.md#self-host-vs-cloud). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.