For AI agents: the complete documentation index is available at /en/llms.txt, the full documentation bundle is available at /en/llms-full.txt, and this page is available as Markdown at /en/guide/quickstart-docker.md.
  • English
  • Octop Docker Setup: Standalone Docker, Compose, and Configuration Reference

    Octop provides a pre-built Docker image that wraps the entire platform — web UI, CLI, IM channels, and agent runtime — into a single container.

    :latest and :<version> are the lite image. Virtual desktop, OCR, and local embedding are on :<version>-full and :full. A local image build is full unless you pass --build-arg OCTOP_IMAGE_VARIANT=lite.

    Choose the setup method that best suits your needs:

    • Standalone Docker (docker run): A fast, single-command startup without cloning the repository. Supports both the Nanjing University China mirror and the official GitHub Packages registry.
    • Docker Compose (docker compose): Recommended for production and multi-user environments with persistent configuration management. Octop provides both a build-free China mirror configuration (docker-compose.cn.yml) and a standard source-build configuration (docker-compose.yml).

    Method 1: Standalone Docker (docker run)

    If you want a lightweight single-command startup without managing complex service dependencies, run docker run directly:

    China Mirror (Recommended for China)
    GitHub Source (Official)

    Uses the Nanjing University mirror proxy for GHCR for faster, reliable downloads within China:

    docker run -d \
      --name octop \
      -p 8088:8088 \
      -v octop-data:/data/.octop \
      -e HOME=/data \
      ghcr.nju.edu.cn/tencentcloud/octop:latest

    Parameter Reference

    ParameterDescription
    --name octopNames the container octop.
    -p 8088:8088Maps container port 8088 to host port 8088. Change the host port if needed (e.g. -p 9090:8088).
    -v octop-data:/data/.octopUses the Docker named volume octop-data to persist databases, keys, and configurations across container restarts and updates. You can also bind mount a host directory, e.g. -v ~/.octop:/data/.octop.
    -e HOME=/dataRequired. Sets the container user home to /data so ~/.octop resolves to the mounted volume path /data/.octop.
    -e OCTOP_DEFAULT_PASSWORD="..."(Optional) Pre-configures the initial admin password (must be ≥ 8 characters and include both letters and digits). If unset, the container launches the web setup wizard on first boot.

    Method 2: Docker Compose Setup

    For production deployments or setups requiring managed environment variables, use Docker Compose. Octop provides two official Compose configuration files:

    China Mirror Configuration (docker-compose.cn.yml)
    Standard / Source Build Configuration (docker-compose.yml)

    Source link: docker-compose.cn.yml

    Highlights:

    • No local build required: Uses the pre-built image from the Nanjing University GHCR mirror ghcr.nju.edu.cn/tencentcloud/octop:latest.
    • No need to clone the repository: You can download this single YAML file and launch it immediately.
    • Optimized for servers in mainland China to eliminate GHCR network latency and failures.

    Quick Start:

    # Step 1: Download the Compose file directly (no git clone required)
    curl -fsSL https://raw.githubusercontent.com/TencentCloud/Octop/main/docker/docker-compose.cn.yml -o docker-compose.cn.yml
    
    # Step 2: Start the container
    docker compose -f docker-compose.cn.yml up -d

    If you have already cloned the Octop repository, run it directly from the repository root:

    docker compose -f docker/docker-compose.cn.yml up -d

    Docker Compose Configuration Breakdown

    Both docker-compose.cn.yml and docker-compose.yml share identical service settings and environment variables:

    1. Service and System Limits (services.octop)

    services:
      octop:
        container_name: octop
        restart: unless-stopped
        ulimits:
          nofile:
            soft: 65535
            hard: 65535
    • restart: unless-stopped: Automatically restarts the container if it crashes or after system reboots.
    • ulimits.nofile: Raises the file descriptor ceiling to 65535, preventing "Too many open files" errors under concurrent WebSocket connections, multi-agent operations, and frequent file I/O.

    2. Ports and Volume Persistence

        ports:
          - "${OCTOP_PORT:-8088}:${OCTOP_PORT:-8088}"
        volumes:
          - ${OCTOP_DATA:-~/.octop}:/data/.octop
    • OCTOP_PORT: Defaults to port 8088. You can override it with an environment variable (e.g. OCTOP_PORT=9090).
    • OCTOP_DATA: Binds the host user's ~/.octop directory to /data/.octop inside the container. Override it via OCTOP_DATA to customize the host storage path (e.g. OCTOP_DATA=/var/lib/octop).

    3. Environment Variables and .env

    Compose files use ${VAR:-default} for parameter interpolation. Place a .env file in the docker/ directory (modeled after .env.example):

    cp .env.example docker/.env
    # Edit docker/.env with your settings
    NOTE

    docker/.env is only used for Compose variable interpolation. Only variables declared under environment: in the Compose file will enter the container. Alternatively, write variables directly to ~/.octop/env in the mounted host directory.

    Supported Compose environment variables include:

    VariableDefaultPurpose and Description
    HOME/dataMust be /data so ~/.octop resolves to the mounted volume path
    OCTOP_BIND_HOST0.0.0.0Listen interface inside the container
    OCTOP_PORT8088HTTP listen port
    OCTOP_LOG_LEVELinfoLogging verbosity (debug, info, warning, error)
    OCTOP_ADMIN_USERNAMEadminFirst-run admin username
    OCTOP_ADMIN_DISPLAY_NAMEAdminFirst-run admin display name
    OCTOP_DEFAULT_PASSWORD(empty)Pre-configured admin password (must be ≥ 8 chars with letters and digits). If unset, the web setup wizard starts
    OCTOP_DATABASE_URL(empty)External database connection string (e.g. PostgreSQL)
    OCTOP_DATABASE_DRIVER(empty)Database driver name, e.g. postgresql
    OPENAI_API_KEY(empty)OpenAI-compatible API key for agent runtime
    DASHSCOPE_API_KEY(empty)Alibaba DashScope (Qwen) API key
    LANGFUSE_TRACING_ENABLEDtrueEnables Langfuse telemetry and trace capture
    LANGFUSE_PUBLIC_KEY(empty)Langfuse public key
    LANGFUSE_SECRET_KEY(empty)Langfuse secret key
    LANGFUSE_BASE_URL(empty)Self-hosted or cloud Langfuse endpoint URL

    First-Run Sign In and Setup Wizard

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

    http://localhost:8088

    The container entrypoint processes initialization based on OCTOP_DEFAULT_PASSWORD:

    Scenario A: Valid password pre-configured

    If you provided a valid OCTOP_DEFAULT_PASSWORD in docker run -e or docker/.env (≥ 8 characters, letters and digits, non-trivial):

    • The container automatically runs octop init and creates the admin user.
    • Login credentials are saved to credential.txt in the volume.
    • Sign in directly with the username (default admin) and your password.

    Scenario B: Password unset or weak (Setup Wizard)

    If OCTOP_DEFAULT_PASSWORD is omitted or does not meet the policy:

    • The container does not loop or fail; it initiates the Web Setup Wizard.
    • A single-use wizard unlocking password is written to octop-login.txt in the data volume (and noted in credential.txt).
    • Open http://localhost:8088 in your browser, enter the wizard password, and configure your admin account.

    Viewing Credentials and Wizard Password

    # Docker Compose (host bind mount ~/.octop)
    cat ~/.octop/octop-login.txt       # Setup wizard password (if password was unset)
    cat ~/.octop/credential.txt        # Credential summary
    
    # Standalone Docker (named volume octop-data)
    docker exec octop cat /data/.octop/octop-login.txt
    docker exec octop cat /data/.octop/credential.txt

    Changing the Admin Password

    After signing in, click Change password in the avatar menu. You can also change the password anytime via CLI on the host:

    docker exec -it octop octop user passwd <username> --password <new-password>
    NOTE

    Changing the password in the web UI will not rewrite credential.txt; the password set in the UI always takes precedence. If you forget your password, see Reset password.


    Useful Operations

    To pull a new image and keep the data volume, see Upgrade.

    # Stream container logs
    docker logs -f octop
    
    # Run a CLI command inside the container (check version)
    docker exec -it octop octop --version
    
    # Stop and remove the container (standalone Docker)
    docker stop octop && docker rm octop
    
    # Stop the Compose service
    docker compose -f docker-compose.cn.yml down
    # or
    docker compose -f docker/docker-compose.yml down
    
    # Check container health status
    curl http://localhost:8088/api/health

    Serve under a subpath

    The default image expects the site at the domain root. To publish it at https://example.com/octop/, rebuild the frontend with VITE_BASE_PATH=/octop/ and strip that prefix in the reverse proxy (proxy_pass with a trailing slash).