• 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 <username> --password <password>

      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. If you forget the password, see Reset password.

      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.

      Use on Tencent Cloud

      Launch a Lighthouse or CVM instance with the official Octop image.

      FnOS NAS

      Install Docker or native .fpk packages on Feiniu NAS.