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:
Uses the Nanjing University mirror proxy for GHCR for faster, reliable downloads within China:
Parameter Reference
Method 2: Docker Compose Setup
For production deployments or setups requiring managed environment variables, use Docker Compose. Octop provides two official Compose configuration files:
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:
If you have already cloned the Octop repository, run it directly from the repository root:
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)
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
OCTOP_PORT: Defaults to port8088. You can override it with an environment variable (e.g.OCTOP_PORT=9090).OCTOP_DATA: Binds the host user's~/.octopdirectory to/data/.octopinside the container. Override it viaOCTOP_DATAto 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):
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:
First-Run Sign In and Setup Wizard
Once the container starts, open your browser and navigate to:
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 initand creates the admin user. - Login credentials are saved to
credential.txtin 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.txtin the data volume (and noted incredential.txt). - Open
http://localhost:8088in your browser, enter the wizard password, and configure your admin account.
Viewing Credentials and Wizard Password
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:
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.
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).
Install Octop directly on macOS, Linux, or Windows without Docker using the one-line installer.
Explore all config.json keys and environment variable overrides for fine-grained control.
Launch a Lighthouse or CVM instance with the official Octop image.
Install Docker or native .fpk packages on Feiniu NAS.

