> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heylinger.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Install with Docker Compose

> Build Linger from source with Docker Compose, create the owner account, and connect your computer.

Docker Compose builds every Linger service from the repository and runs it, PostgreSQL and voice included. Use this path instead of the desktop app when you build from source, or when one server serves several computers on your network.

The containers do not run your agents. Your agents run on a Computer: a machine that you connect to the server. That Computer needs Claude Code, Codex, or Pi installed and signed in.

Linger needs no model gateway or API key of its own. Agent model calls run on the Claude Code, Codex, or Pi of your own computer. The background work for memory and the personal memory runs on the Codex or Claude Code there. Grok Live voice mode is the one exception: the server calls xAI directly when you set `XAI_API_KEY`.

## Check what you need

You need Docker with Compose and one computer that can run your agents.

* Docker with Compose, with at least 5 GiB of memory for its virtual machine. The web app build alone uses about 4 GB.
* Git, to clone the repository.
* A computer with Claude Code, Codex, or Pi installed and signed in.

## Build and start the server

**1. Clone the repository**

```bash theme={null}
git clone https://github.com/simplexai-labs/linger.git
cd linger
```

**2. Create the environment file**

```bash theme={null}
cp .env.example .env
```

**3. Build and start the services**

```bash theme={null}
docker compose up --build --detach --wait
```

**4. Create the owner account**

Replace the email and the password with your own. The password goes in through standard input.

```bash theme={null}
printf '%s\n' 'choose-a-password' | docker compose exec -T teamhub \
  teamhub-account create-owner --email you@example.com --password-stdin
```

**5. Sign in**

Open `http://localhost:3000` and sign in with the owner account.

Linger cannot reset a lost password by email. To set a new password, run the same command with `set-password` instead of `create-owner`.

## Connect your computer

After you sign in, a **Connect your computer** dialog covers the app. It shows the commands for your platform and stays open until a computer with Claude Code, Codex, or Pi signed in comes online. On macOS and Linux, the commands look like this.

```bash theme={null}
curl -fsSL "http://localhost:3000/install/linger-computer.sh" | bash
linger-computer login
```

On Windows, use an ordinary PowerShell that does not run as administrator.

```powershell theme={null}
irm "http://localhost:3000/install/linger-computer.ps1" | iex
linger-computer login
```

`linger-computer login` authorizes the computer in the browser and starts the Computer Daemon. Then run `linger-computer daemon status` to check the connection. If agents do not answer, run `linger-computer runtime check`. See [Choose a runtime](https://docs.heylinger.com/models/choose-a-runtime.md).

## Serve other computers on your network

By default, the server is for `localhost` only. To serve other computers, set four variables in `.env` and run `docker compose up --detach --wait` again. Replace `192.168.1.10` with this computer's address.

```bash theme={null}
WEB_BIND_ADDRESS=0.0.0.0
WEB_PUBLIC_ORIGIN=http://192.168.1.10:3000
AGENT_RUNNER_PUBLIC_GATEWAY_URL=ws://192.168.1.10:3000/v1/runner-gateway
LINGER_SECRET_SEED=<output of: openssl rand -base64 32>
```

Browsers and Computers then reach everything through port 3000.

> [!WARNING]
>
> `.env.example` ships a public development seed and encryption key. Everyone has these values. Before you serve other computers, generate private values for `LINGER_SECRET_SEED` and `TEAMHUB_SECRET_ENCRYPTION_KEY` with `openssl rand -base64 32`. Put HTTPS in front of port 3000.

Linger refuses to start with the public seed once `WEB_PUBLIC_ORIGIN` is not `localhost`, `127.0.0.1`, or `::1`. Plain HTTP exposes sign-in cookies and the Computer connection to anyone on the network. See [Serve other computers on your network](https://docs.heylinger.com/admin/network.md).

## Turn on voice

Voice needs a [Soniox](https://soniox.com) key in `SONIOX_API_KEY`. Docker Compose already runs LiveKit and the voice workers. Set the key in `.env` and run `docker compose up --detach --wait` again. Browsers allow the microphone only on `localhost` or HTTPS. See [Enable voice](https://docs.heylinger.com/admin/voice.md).

## Fix common problems

Most problems are a service that did not start or a Computer that cannot connect.

| Problem | What to try |
| - | - |
| The app does not open | Run `docker compose ps`, then `docker compose logs <service>`. |
| The Computer shows offline, or agents never answer | On that Computer, run `linger-computer daemon status` and `linger-computer doctor`. Read `linger-computer daemon logs`, then try `linger-computer daemon restart`. |
| "No runtime is ready yet" | Run `linger-computer runtime check`. Add `codex --live` to wait for a real model reply. |
| Other computers cannot connect | Set the four variables above and run `docker compose up --detach --wait` again. |
| The microphone is blocked | Put an HTTPS proxy in front of port 3000. |

For more cases, see [Troubleshooting](https://docs.heylinger.com/admin/troubleshooting.md).

## Keep learning

> [card] [Choose a runtime](https://docs.heylinger.com/models/choose-a-runtime.md)
>
> Check that your Runtime is ready on the connected Computer.

> [card] [Serve other computers on your network](https://docs.heylinger.com/admin/network.md)
>
> Serve Linger on your network and add HTTPS.

> [card] [Environment variables](https://docs.heylinger.com/reference/environment-variables.md)
>
> See the settings in the `.env` file.


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