• English

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

      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.

      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
      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. Set OCTOP_DEFAULT_PASSWORD for the first admin password; omit it to generate a random one.

      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="<strong-password-or-omit-for-random>" \
  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.

      Open the web UI and sign in

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

      http://localhost:8088

      Sign in with the username and password in credential.txt. Compose bind-mounts the host ~/.octop to /data/.octop, so both paths are the same file:

      # Compose (host bind mount)
cat ~/.octop/credential.txt

# Named volume or any deployment
docker exec octop cat /data/.octop/credential.txt
      NOTE

      Override the username with OCTOP_ADMIN_USERNAME. Bare-metal first-run steps are in Quickstart. Password rules and how to change it are in First-run password.

      To verify the container is healthy before opening the web UI, run:

      curl http://localhost:8088/api/health

      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.

      First-run password

      The entrypoint runs octop init once, only when the volume has no octop.db yet. It writes the URL, username, and password to /data/.octop/credential.txt inside the container (chmod 600). This is not ~/octop-login.txt (that file is for a bare-metal octop init / setup wizard).

      SituationResult
      OCTOP_DEFAULT_PASSWORD unsetGenerate a 16-character random password and write it to credential.txt
      You set a password that meets the policyUse your value
      You set a weak or common passwordRetry with a random password so first init never fails

      A password you set must be at least 8 characters, include a letter and a digit, and must not be a common value such as password123, admin123, or octop123. Set OCTOP_DEFAULT_PASSWORD in docker/.env or with docker run -e.

      After you sign in, change the password from the avatar menu (Change password), or run:

      docker exec -it octop octop user passwd admin

      Changing the password in the web UI does not rewrite credential.txt — the password you set in the UI wins. Do not leave the generated or bootstrap password on a host that is reachable from the network.

      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.

      VariableDefaultDescription
      OCTOP_PORT8088HTTP listen port inside the container
      OCTOP_DATA~/.octopHost directory for the Compose bind mount (maps to /data/.octop in the container)
      HOME/dataMust be /data so that ~/.octop resolves to the mounted volume path
      OCTOP_ADMIN_USERNAMEadminFirst-run admin username
      OCTOP_ADMIN_DISPLAY_NAMEAdminFirst-run admin display name
      OCTOP_DEFAULT_PASSWORD(unset)First-run admin password. Unset generates a random password and writes it to credential.txt. Weak or common values fall back to a random password
      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 from the avatar menu (Change password). Do not leave the generated or bootstrap password 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.