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

# Octop Docker Setup: Compose, Volumes, and Environment Vars

> Deploy Octop using Docker Compose or a standalone docker run command. Includes volume mounts, environment variables, and first-run setup.

Octop ships a pre-built Docker image that wraps the full platform — web UI, CLI, IM channels, and the agent runtime — in a single container. Docker Compose is the recommended approach for production and multi-user deployments because it handles volume mounts and environment configuration out of the box. All your data persists in a named volume (or a host bind mount), so upgrades never touch your conversations, agents, or credentials.

**1. Pull and start with Docker Compose**

From the root of the cloned repository, start Octop with a single command:

```bash theme={null}
docker compose -f docker/docker-compose.yml up -d --build
```

Docker Compose builds the image from source, mounts your host `~/.octop` directory into the container at `/data/.octop`, and starts the server in detached mode.

To pass custom environment variables (API keys, port overrides, etc.), create a `docker/.env` file before running the command:

```bash theme={null}
cp .env.example docker/.env
# Edit docker/.env with your values, then:
docker compose -f docker/docker-compose.yml up -d --build
```

> [!TIP]
>
> Set `OCTOP_DATA` in `docker/.env` to choose a custom host directory for all persistent data. This makes it easy to back up or migrate your entire Octop instance by copying a single directory.

**2. Or start with a standalone docker run**

If you prefer not to use Compose, build the image manually and run the container directly:

```bash theme={null}
# Build the image from source
bash docker/docker_build.sh

# Run the container
docker run -d \
  --name octop \
  -p 8088:8088 \
  -v octop-data:/data/.octop \
  -e HOME=/data \
  -e OCTOP_DEFAULT_PASSWORD=Octop123 \
  octop:latest
```

The named volume `octop-data` persists your database, secrets, and agent workspaces across container restarts and upgrades. The image does **not** include Playwright Chromium. Re-run the installer with `--extras browser` on the host, or add the `browser` extra in your image, if you need workbench browser automation.

> [!NOTE]
>
> The `HOME=/data` environment variable is required so that `~/.octop` resolves to `/data/.octop` inside the container, where the named volume is mounted.

**3. Open the web UI and complete first-run setup**

Once the container starts, open your browser and navigate to:

```
http://localhost:8088
```

First boot creates a fixed admin account: username `admin`, password `Octop123`. Octop writes those credentials to `/data/.octop/credential.txt` inside the container. This is **not** a random password and is **not** `~/octop-login.txt` (that file is for a bare-metal `octop init` / setup wizard). Change the password immediately after you sign in.

> [!NOTE]
>
> Override the defaults with `OCTOP_ADMIN_USERNAME` and `OCTOP_DEFAULT_PASSWORD`. Bare-metal first-run steps are in [Quickstart](https://octop.mintlify.site/quickstart.md).

To verify the container is healthy before opening the wizard, run:

```bash theme={null}
curl http://localhost:8088/api/health
```

**4. Configure a model provider**

Octop ships built-in presets for Tencent Cloud, OpenAI, Anthropic, DeepSeek, Ollama, and many more. Add your first provider directly from the web UI:

```text theme={null}
Management → Models
```

Pick a built-in preset, enter your API key, and enable it. You can also pass common API keys as environment variables so they are available to the agent runtime immediately on first boot:

```bash theme={null}
docker run -d \
  --name octop \
  -p 8088:8088 \
  -v octop-data:/data/.octop \
  -e HOME=/data \
  -e OPENAI_API_KEY=sk-... \
  octop:latest
```

Once the provider is configured, open the **Chat** section in the web UI and start your first conversation.

## Environment variables

Use these variables to configure Octop's Docker deployment. For Docker Compose, add them to `docker/.env`. For `docker run`, pass them with `-e KEY=value`.

| Variable | Default | Description |
| - | - | - |
| `OCTOP_PORT` | `8088` | HTTP listen port inside the container |
| `OCTOP_DATA` | `~/.octop` | Host directory for the Compose bind mount (maps to `/data/.octop` in the container) |
| `HOME` | `/data` | Must be `/data` so that `~/.octop` resolves to the mounted volume path |
| `OCTOP_ADMIN_USERNAME` | `admin` | First-run admin username |
| `OCTOP_DEFAULT_PASSWORD` | `Octop123` | First-run admin password (Docker bootstrap) |
| `OPENAI_API_KEY` | — | OpenAI-compatible API key, made available to the agent runtime |
| `DASHSCOPE_API_KEY` | — | Alibaba DashScope (Qwen) API key |

> [!NOTE]
>
> After the first boot, change the password under **Management → Users**. Do not leave `Octop123` on a host that is reachable from the network.

## Useful operations

```bash theme={null}
# Follow container logs
docker logs -f octop

# Run a CLI command inside the running container
docker exec -it octop octop --version

# Stop the Compose stack
docker compose -f docker/docker-compose.yml down

# Rebuild and restart after a code update
docker compose -f docker/docker-compose.yml up -d --build
```

> [card] [Bare-metal Quickstart](https://octop.mintlify.site/quickstart.md)
>
> Install Octop directly on macOS, Linux, or Windows without Docker using the one-line installer.

> [card] [Configuration Reference](https://octop.mintlify.site/configuration/config-file.md)
>
> Explore all `config.json` keys and environment variable overrides for fine-grained control.

> [card] [FnOS NAS](https://octop.mintlify.site/guides/fnos.md)
>
> Install Docker or native `.fpk` packages on Feiniu NAS.


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