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

# Self-hosting walkthrough

> Go from a fresh server to a working GAIA your whole household or team can use, one step at a time, with screenshots.

Go from an empty server to a GAIA your team uses, in about ten minutes.

You need a server or computer with 8 GB of RAM, and an API key from one AI provider such as OpenAI.

## Install and start GAIA

**1. Install the GAIA CLI**

Open a terminal on the server and run:

```bash theme={null}
curl -fsSL https://heygaia.io/install.sh | sh
```

It installs Node.js and the GAIA CLI, then asks whether to set GAIA up now. Say yes and it runs `gaia up` for you, so you can skip the next step.

![The GAIA installer under the GAIA logo: Node.js, the GAIA CLI and Docker installed, setup files fetched, then Downloading GAIA at 52%, 1.5 of 2.7 GB with about 2 minutes left, and a row per image: web app done, the rest unpacking or downloading](https://mintcdn.com/gaia-a3e7b78f/aiZIEOOyBrv-z9zE/images/self-hosting/terminal-install.webp?fit=max\&auto=format\&n=aiZIEOOyBrv-z9zE\&q=85\&s=f1455dbc83322da96368672e4c237b1d)

The installer carries straight on into gaia up and downloads GAIA

**2. Run gaia up**

```bash theme={null}
gaia up
```

It installs Docker if needed, downloads GAIA and starts it. When it finishes, it prints the address to open.

![The end of a GAIA install: every step checked with its time, then a box reading GAIA is running, ready in 10m 24s, Next: open the .local setup link to create your admin account, also at http://localhost:3000, and the gaia status, stop, doctor and help commands below](https://mintcdn.com/gaia-a3e7b78f/aiZIEOOyBrv-z9zE/images/self-hosting/terminal-gaia-up.webp?fit=max\&auto=format\&n=aiZIEOOyBrv-z9zE\&q=85\&s=7700cab7edcbce842d3afd8537505487)

gaia up finishes with the one link to open next

Want your AI provider saved at the same time? Add it here and skip that step in the browser:

```bash theme={null}
gaia up --llm-provider openai --llm-key sk-...
```

> **More options (domain, port, Ollama, other providers)**
>
> | Flag | What it does |
> | - | - |
> | `--domain <domain>` | Serves GAIA at `https://<domain>` with an automatic certificate. Uses ports 80 and 443 |
> | `--web-port <port>` | Changes the port. Default 3000 |
> | `--llm-provider <name>` | `openai`, `openrouter`, `gemini`, `ollama` or `custom` |
> | `--llm-key <key>` | The provider's key. Not used with `ollama` |
> | `--llm-base-url <url>` | The provider's address. Needed for `custom` |
> | `--llm-model <model>` | The model. Needed for `custom` |
> | `--code-sandbox` | Turns on the local code sandbox. See [Run code](#run-code-optional) |
>
> ```bash theme={null}
> # A local Ollama: no key
> gaia up --llm-provider ollama --llm-model qwen3
>
> # Any OpenAI-compatible gateway
> gaia up --llm-provider custom --llm-key sk-... --llm-base-url https://gateway.example.com/v1 --llm-model some-model
> ```
>
> The provider is saved like the browser setup saves it, so you can change it later in **Settings → Providers & Tools**. If GAIA is slow to start, `gaia up` says the provider wasn't saved. Run the same command again once `gaia status` shows GAIA healthy. Every flag is in the [CLI reference](https://docs.heygaia.io/self-hosting/cli-reference.md#gaia-up).

**3. Open the printed address**

On the server, `http://localhost:3000` works. From another device on your network, use the `192.168.x.x` address.

## Finish setup in the browser

**1. Create the admin account**

The first account is the admin. Use a password of at least 8 characters.

![Setup step titled Create your admin account, with the name Ada Lovelace, the email ada@example.com and a hidden password filled in, above a Create account button](https://mintcdn.com/gaia-a3e7b78f/aiZIEOOyBrv-z9zE/images/self-hosting/setup-admin-account.webp?fit=max\&auto=format\&n=aiZIEOOyBrv-z9zE\&q=85\&s=f4e56b0b7c0d092d62a26a142f18e31a)

The first account becomes the admin

**2. Connect an AI provider**

GAIA needs one AI provider. If you passed `--llm-provider`, press **Continue**. Otherwise pick one:

| Tab | What you do |
| - | - |
| **Hosted key** | Paste an OpenRouter key, or click **More providers** for OpenAI, Google Gemini or a custom OpenAI-compatible server. Then click **Test & Save** |
| **Local Ollama · free** | Use an Ollama running on your machine. No key needed |
| **Skip for now** | Set it up later. GAIA can't chat until you do |

![Setup step titled Choose an AI provider, showing OpenAI is connected and saved on this instance, with Change provider, Back, Continue and Skip for now](https://mintcdn.com/gaia-a3e7b78f/aiZIEOOyBrv-z9zE/images/self-hosting/setup-ai-provider.webp?fit=max\&auto=format\&n=aiZIEOOyBrv-z9zE\&q=85\&s=0ef0d35abde7242455524df4c945194f)

OpenAI connected with a pasted key

**3. Add the optional extras, or skip them**

The next screens are optional. Paste a key if you have one, or press **Continue**:

* **Web search** works for free with DuckDuckGo. Tavily, Exa, Brave Search or your own SearXNG give better results.
* **Tool keys** such as Composio and E2B, and apps you can connect.

Then click **Start chatting**. Add keys any time in **Settings → Providers & Tools**; see [AI models and tools](https://docs.heygaia.io/self-hosting/ai-models-and-tools.md#tools).

![Setup step titled Web search, using DuckDuckGo for free with no key, a Provider picker set to Tavily with an API key field and a Save button, and Back, Continue and Skip for now](https://mintcdn.com/gaia-a3e7b78f/aiZIEOOyBrv-z9zE/images/self-hosting/setup-web-search.webp?fit=max\&auto=format\&n=aiZIEOOyBrv-z9zE\&q=85\&s=dc98ec99c78510da97aba2a92b167a23)

An optional step: better web search with a Tavily, Exa or Brave key

**4. Land on the home screen**

A banner lists optional features that are still off. Click **Show** to see them, or **Set up** to add one.

![Setup banner reading 3 setup steps left, opened to list Email, Integrations and Weather, each with a Set up button and a dismiss cross](https://mintcdn.com/gaia-a3e7b78f/aiZIEOOyBrv-z9zE/images/self-hosting/home-setup-banner.webp?fit=max\&auto=format\&n=aiZIEOOyBrv-z9zE\&q=85\&s=c11255fc37201fae1a354b736c3cf05c)

The setup banner, opened with Show

> **Setup banner vs First steps**
>
> | | Setup banner | First steps |
> | - | - | - |
> | Who sees it | Only the admin | Every member, each their own |
> | What it tracks | The server: AI provider, then optional features still off | You: say hi, connect an app, link a messaging app, create a workflow |
> | Where | Top of the home screen | Bottom-right panel (not on phones) and a dashboard card |
> | Goes away | When nothing is left, or when you hide it | When every step is done, or when you collapse it |

## Use GAIA

### Your first chat

Type a message and press Enter.

![Chat where the user asks what GAIA can help with, and GAIA lists calendar, email, reminders, todos, connected apps, files and workflows](https://mintcdn.com/gaia-a3e7b78f/aiZIEOOyBrv-z9zE/images/self-hosting/first-chat.webp?fit=max\&auto=format\&n=aiZIEOOyBrv-z9zE\&q=85\&s=699d5f5bcff2b1edbaaabf51d49455c1)

A first message and GAIA's reply

### Todos and tools

Ask GAIA to do something, like adding a todo.

![Chat where the user asks to add a todo to renew their passport by Friday, and GAIA confirms it is set for Friday, October 16](https://mintcdn.com/gaia-a3e7b78f/aiZIEOOyBrv-z9zE/images/self-hosting/todo-from-chat.webp?fit=max\&auto=format\&n=aiZIEOOyBrv-z9zE\&q=85\&s=b1bf5203ea1a470c6a155137ced7ae9a)

Adding a todo from chat

The todo shows up under **Tasks**.

![Tasks page listing the todo Renew my passport, due Friday, October 16, in the Inbox](https://mintcdn.com/gaia-a3e7b78f/aiZIEOOyBrv-z9zE/images/self-hosting/todos-page.webp?fit=max\&auto=format\&n=aiZIEOOyBrv-z9zE\&q=85\&s=d8450f9bd681717089084943a9dc3d15)

The new todo in Tasks

### Run code (optional)

GAIA can run code only if you turn on a sandbox:

* **E2B** (recommended): save an [E2B](https://e2b.dev) key in **Settings → Providers & Tools**. Code runs on E2B's servers.
* **Local sandbox**: run `gaia up --code-sandbox`. Code runs on your own server.

> [!WARNING]
>
> The local sandbox gives GAIA root-level access to your server. Use it only where you trust everyone. Turn it off with `gaia up --no-code-sandbox`. See [Running code](https://docs.heygaia.io/self-hosting/ai-models-and-tools.md#running-code).

![Chat where the user asks GAIA to run Python that prints the 20th Fibonacci number, and GAIA shows the output 6765](https://mintcdn.com/gaia-a3e7b78f/aiZIEOOyBrv-z9zE/images/self-hosting/code-sandbox-chat.webp?fit=max\&auto=format\&n=aiZIEOOyBrv-z9zE\&q=85\&s=87f5622628deaa9d5b6705d23f1d13df)

GAIA runs Python in the sandbox and shows the output

### Upload files and images

Use the **+** button in the message box. Files stay on your server.

![Chat with an uploaded image of a red circle and the word HELLO, and GAIA's reply: a red circle, the colour red, and the word HELLO](https://mintcdn.com/gaia-a3e7b78f/aiZIEOOyBrv-z9zE/images/self-hosting/image-understanding.webp?fit=max\&auto=format\&n=aiZIEOOyBrv-z9zE\&q=85\&s=b7cbe595fa62f5c9e00d467f28a4995f)

GAIA reads an uploaded image

## Change settings later

### Providers & Tools

Open **Settings → Providers & Tools** to change AI providers, web search or the code sandbox. Changes apply right away.

![Providers and Tools settings: AI models marked Working and using OpenAI, with the provider picker, the stored key, the model and Remove, Test and Test and Save buttons; Web search marked Working and using DuckDuckGo, with a provider picker set to Tavily and a Save button](https://mintcdn.com/gaia-a3e7b78f/aiZIEOOyBrv-z9zE/images/self-hosting/settings-providers-tools.webp?fit=max\&auto=format\&n=aiZIEOOyBrv-z9zE\&q=85\&s=47d84ad60127d7452210d55e13b766cb)

Settings → Providers & Tools

### Connect apps like Gmail and Calendar

Apps connect through your own Composio project. Paste its key in **Settings → Integrations setup**. Full steps: [Connect integrations](https://docs.heygaia.io/self-hosting/composio-integrations.md).

![Integrations setup settings with a Composio API key field, a Browse Composio catalog button, and integrations such as Google Calendar, Google Docs, Google Drive, Gmail and Notion, each not set up yet](https://mintcdn.com/gaia-a3e7b78f/aiZIEOOyBrv-z9zE/images/self-hosting/settings-integrations-setup.webp?fit=max\&auto=format\&n=aiZIEOOyBrv-z9zE\&q=85\&s=6e0fed33a9c84a298c4e64ff9be385fb)

Settings → Integrations setup

## Invite other people

**1. Create an invite link**

Open **Settings → Members** and press **Create link**. Copy it right away and send it. Each link works once and expires after 7 days.

Everyone gets private chats, tasks and apps. They share your AI keys, which only you can change.

![Members settings with the Open sign-up switch off, a freshly created invite link with a copy button, the unused invite with a Revoke button, and Ada Lovelace listed as Admin](https://mintcdn.com/gaia-a3e7b78f/aiZIEOOyBrv-z9zE/images/self-hosting/settings-members-invite.webp?fit=max\&auto=format\&n=aiZIEOOyBrv-z9zE\&q=85\&s=a596df4a0a6514cedffe15dffe5047c3)

Settings → Members, with a new invite link

Or turn on **Open sign-up** to let anyone who can reach your GAIA join.

**2. Your teammate signs up**

They open the link and create an account.

![Create your account page reading Join this GAIA instance, filled in with the name Grace Hopper and the email grace@example.com](https://mintcdn.com/gaia-a3e7b78f/aiZIEOOyBrv-z9zE/images/self-hosting/member-signup.webp?fit=max\&auto=format\&n=aiZIEOOyBrv-z9zE\&q=85\&s=9792a66adc39220b72fea9fe78c774e8)

Signing up from an invite link

They land on their own home screen.

![GAIA home screen greeting Grace by name, with the message box and suggested prompts](https://mintcdn.com/gaia-a3e7b78f/aiZIEOOyBrv-z9zE/images/self-hosting/member-home.webp?fit=max\&auto=format\&n=aiZIEOOyBrv-z9zE\&q=85\&s=c59d4e32e57d0ae9b6e0cffa25d79658)

The new member's own GAIA

If a link was used or expired, create a new one.

**3. Sign in next time**

Everyone signs in with email and password at the same address.

![Welcome back sign-in page with email and password fields, a Sign in button and a link to sign up](https://mintcdn.com/gaia-a3e7b78f/aiZIEOOyBrv-z9zE/images/self-hosting/login-page.webp?fit=max\&auto=format\&n=aiZIEOOyBrv-z9zE\&q=85\&s=f07921342671f6b92ce49b24c73c51d2)

The sign-in page

## Check on it

Run `gaia status` to see if each part is running. If something seems wrong, run `gaia doctor`. It prints a fix for each problem.

![Terminal output of gaia status: GAIA is running at its .local address; the web app, server, background jobs and proxy, and MongoDB, PostgreSQL, Redis, RabbitMQ and ChromaDB all checked; no bots yet; setup not finished, with the link to finish it](https://mintcdn.com/gaia-a3e7b78f/aiZIEOOyBrv-z9zE/images/self-hosting/terminal-gaia-status.webp?fit=max\&auto=format\&n=aiZIEOOyBrv-z9zE\&q=85\&s=3ac92eb57d1c8b776728971a52e3058f)

gaia status: every dependency and container

## Update and back up

```bash theme={null}
gaia update
```

Your chats, accounts and settings stay. For a newer GAIA, run the install command again first.

```bash theme={null}
gaia backup
```

Backups go to `./backups/`. See [Backups](https://docs.heygaia.io/self-hosting/maintenance.md#backups) to restore and store them safely.

## Next steps

> **[Connect integrations](https://docs.heygaia.io/self-hosting/composio-integrations.md)**
>
> Gmail, Calendar, GitHub and more through your own Composio project

> **[CLI setup](https://docs.heygaia.io/self-hosting/cli-setup.md)**
>
> Every `gaia` command and flag

> **[AI models and tools](https://docs.heygaia.io/self-hosting/ai-models-and-tools.md)**
>
> Change the AI provider and add optional tools

> **[Deploy options](https://docs.heygaia.io/self-hosting/one-click-deploy.md)**
>
> DigitalOcean, Coolify, Render and Railway, with costs and test status


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.