AI models and tools

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	`OPENROUTER_API_KEY`	One key for most models. Easiest start
Google Gemini	A key from aistudio.google.com/apikey	`GOOGLE_API_KEY`	Has a free tier
OpenAI	A key from 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
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

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.

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.

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 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.

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:

BLOB_STORE=s3
S3_ENDPOINT_URL=https://<account-id>.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. MCP servers 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.

Get Started

Configure

Connect Apps

Use It Everywhere

Maintain

Reference

Where you change things

AI models

From the terminal

Using Ollama

Tools

Web search

Running code

File storage

Using an S3 bucket

Integrations

Not available on self-host

​Where you change things

​AI models

​From the terminal

​Using Ollama

​Tools

​Web search

​Running code

​File storage

​Using an S3 bucket

​Integrations

​Not available on self-host

Where you change things

AI models

From the terminal

Using Ollama

Tools

Web search

Running code

File storage

Using an S3 bucket

Integrations

Not available on self-host