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:

   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:

   cp .env.example docker/.env
   # Edit docker/.env with your values, then:
   docker compose -f docker/docker-compose.yml up -d --build
   

   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:

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

   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.

   Override the defaults with OCTOP_ADMIN_USERNAME and OCTOP_DEFAULT_PASSWORD. Bare-metal first-run steps are in Quickstart.

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

   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:

   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:

   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

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

# 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

Bare-metal Quickstart

Install Octop directly on macOS, Linux, or Windows without Docker using the one-line installer.

Configuration Reference

Explore all config.json keys and environment variable overrides for fine-grained control.

FnOS NAS

Install Docker or native .fpk packages on Feiniu NAS.