Octop Environment Variables: Complete Config Reference#
Every setting in config.json has a matching environment variable. When you set one, it takes priority over the value in the file — the file itself is never modified. This makes environment variables the preferred approach for Docker deployments, CI pipelines, and any situation where you want to keep secrets out of the filesystem.
#Variable reference
| Variable | Type | Default | Description |
|---|---|---|---|
OCTOP_HOME | path | ~/.octop | Installation root. All data — database, secrets, agent workspaces, plugins — is stored here. |
OCTOP_BIND_HOST | string | 127.0.0.1 | Interface Octop listens on. Set to 0.0.0.0 for LAN or container access. |
OCTOP_PORT | int | 8088 | TCP port Octop binds to. |
OCTOP_LOG_LEVEL | string | info | Log verbosity: debug, info, warning, or error. |
OCTOP_LOG_RETENTION_DAYS | int | 14 | Keep rotated octop.log.YYYY-MM-DD files for this many days. |
OCTOP_LOG_MAX_BYTES | int | 104857600 (100 MiB) | Roll the active log when it exceeds this size, in addition to daily rotation. |
OCTOP_LOG_COMPRESS | bool | true | logrotate-style compress + delaycompress: gzip older rotated plains on the next cycle. |
OCTOP_ACCESS_TOKEN_TTL | int (seconds) | 86400 | JWT access-token lifetime. Default is 24 hours. |
OCTOP_LOGIN_MAX_ATTEMPTS | int | 5 | Failed login attempts before an account is locked out. |
OCTOP_LOGIN_LOCKOUT_SECONDS | int | 900 | How long (seconds) a lockout lasts after too many failed attempts. |
OCTOP_CAPTCHA_PROVIDER | slug | slider | Login captcha: slider, turnstile, hcaptcha, recaptcha-v3, or tencent. recaptcha (v2) still works if already stored, but is unlisted. Boot snapshot; restart after you change it. |
OCTOP_CAPTCHA_SITE_KEY | string | (empty) | Public site key (Tencent: CaptchaAppId). Required when the env snapshot is a strong provider. |
OCTOP_CAPTCHA_SECRET | string | (empty) | Siteverify secret (Tencent: AppSecretKey). Never logged; GET /api/envs redacts it. |
OCTOP_CAPTCHA_CAM_SECRET_ID | string | (empty) | Tencent only: CAM API SecretId for DescribeCaptchaResult. Required when the env snapshot is tencent. |
OCTOP_CAPTCHA_CAM_SECRET_KEY | string | (empty) | Tencent only: CAM API SecretKey. Never logged; GET /api/envs redacts it. |
OCTOP_CAPTCHA_V3_MIN_SCORE | float | 0.5 | Minimum recaptcha-v3 score. The admin UI is read-only for this value. |
OCTOP_DEFAULT_TIMEZONE | IANA tz | Asia/Shanghai | Timezone for dashboard timestamps, cron scheduling, and the agent harness. |
OCTOP_CORS_ORIGINS | comma-sep | (empty) | Comma-separated list of origins permitted to make cross-origin requests. |
OCTOP_ENABLE_DASHBOARD | bool | true | Serve the built-in React SPA at /. |
OCTOP_ENABLE_API_DOCS | bool | false | Expose the interactive Scalar API docs at /api/docs. |
OCTOP_REQUIRE_SETUP_PASSWORD | bool | true | Require a password gate during the first-run setup wizard. Set to false for unattended bootstraps using OCTOP_ADMIN_USERNAME / OCTOP_ADMIN_PASSWORD. |
OCTOP_DATABASE_URL | string | (empty) | Full PostgreSQL DSN (e.g. postgresql://user:pass@host:5432/octop). Overrides all individual OCTOP_DATABASE_* fields below. |
OCTOP_DATABASE_DRIVER | string | sqlite | Storage backend: sqlite or postgresql. |
OCTOP_DATABASE_SQLITE_PATH | path | octop.db | SQLite file path. Relative paths resolve from OCTOP_HOME. |
OCTOP_DATABASE_HOST | string | 127.0.0.1 | PostgreSQL host. Used only when OCTOP_DATABASE_DRIVER=postgresql. |
OCTOP_DATABASE_PORT | int | 5432 | PostgreSQL port. |
OCTOP_DATABASE_NAME | string | octop | PostgreSQL database name. |
OCTOP_DATABASE_USER | string | octop | PostgreSQL user. |
OCTOP_DATABASE_PASSWORD | string | (empty) | PostgreSQL password. Always set this via environment rather than config.json in production. |
OCTOP_ADMIN_USERNAME | string | (empty) | Pre-fills the first admin username during octop init. Use with OCTOP_ADMIN_PASSWORD for unattended bootstraps. Docker first boot defaults to admin if unset. |
OCTOP_ADMIN_PASSWORD | string | (empty) | Pre-fills the first admin password during octop init. |
OCTOP_DEFAULT_PASSWORD | string | (empty) | Docker / image first-boot admin password. Written to /data/.octop/credential.txt. Unset generates a 16-character random password. Weak or common values fall back to a random password so first init never fails. Does not replace the bare-metal setup wizard. |
OCTOP_ADMIN_DISPLAY_NAME | string | (empty) | Pre-fills the display name of the first admin account during octop init. |
OCTOP_HISTORY_V2_ENABLED | — | ignored | Retired. Octop ignores this variable and migrates an existing v2 archive on startup. |
OCTOP_BROWSER_IDLE_TIMEOUT_MINUTES | int | 30 | Idle minutes before Octop reaps a local Chrome started from the workbench. |
OCTOP_USER | string | (empty) | Default --user value for CLI subcommands, so you can omit the flag. |
OCTOP_AGENT | string | (empty) | Default --agent value for CLI subcommands. |
OCTOP_SERVICE_MODE | string | (auto) | Override the service backend used by octop service. Accepted values: systemd or launchd. Normally auto-detected from the host OS. |
OCTOP_SERVICE_SCOPE | string | (auto) | Control whether octop service installs a user-level or system-level unit on Linux. Accepted values: user or system. Equivalent to passing --scope to octop service start. |
OCTOP_MAX_UPLOAD_MB | int | 100 | Max upload size in MiB for chat attachments, IM inbound files, and knowledge documents (clamped to 1–1024). Does not apply to plugin ZIPs, workspace uploads, or backup import (backup import is 512 MB). |
OCTOP_BACKUP_AUTO_ENABLED | bool | false | Enable automatic backups inside a running octop run process. |
OCTOP_BACKUP_SCHEDULE | string | cron:0 4 * * * | Automatic backup schedule. |
OCTOP_BACKUP_RETENTION_COUNT | int | 7 | How many automatic backup archives to keep. |
OCTOP_BACKUP_INCLUDE_CONFIG | bool | true | Include config.json and env in new archives. |
OCTOP_BACKUP_INCLUDE_WORKSPACES | bool | true | Include agent workspaces. |
OCTOP_BACKUP_INCLUDE_SKILL_PACKAGES | bool | true | Include global skill packages. |
OCTOP_BACKUP_INCLUDE_PLUGINS | bool | true | Include installed plugins. |
OCTOP_BACKUP_INCLUDE_KNOWLEDGE | bool | true | Include knowledge-base files. |
OCTOP_BACKUP_INCLUDE_CHATS | bool | false | Include chat history and trajectories. |
OCTOP_PORTAL_ORIGIN | origin | https://octop.cloud | Plugin and expert catalog origin. Scheme, host, and port only. An empty string disables the remote catalog. See Plugin and expert market. |
OCTOP_MARKET_REMOTE_ORIGIN | origin | https://download.octop.cloud | Origin allowed for catalog download_url values. Scheme, host, and port only. See Plugin and expert market. |
SKILL_MARKET_ORIGIN | origin | https://api.skillhub.cn | Skill search, rankings, and ZIP download. Scheme, host, and port only. See Skill market. |
SKILLSET_ORIGIN | origin | https://api.skillhub.cn | Skillset detail used by Import from skill market. Scheme, host, and port only. See Skill market. |
OCTOP_CHECKPOINT_BACKUP_BEFORE_PRUNE | string | first | Before scheduled checkpoint cleanup, write memory.sqlite.pre-prune.bak. always replaces that backup every time and skips pruning if the backup cannot be written. off skips the backup. |
OCTOP_CHECKPOINT_BACKUP_KEEP_DAYS | int | 7 | Days to keep that checkpoint backup. 0 disables expiration. |
#Docker .env example
Create a .env file next to your docker-compose.yml and populate the variables relevant to your deployment:
# Network
OCTOP_BIND_HOST=0.0.0.0
OCTOP_PORT=8088
# Database (PostgreSQL)
OCTOP_DATABASE_DRIVER=postgresql
OCTOP_DATABASE_HOST=postgres
OCTOP_DATABASE_PORT=5432
OCTOP_DATABASE_NAME=octop
OCTOP_DATABASE_USER=octop
OCTOP_DATABASE_PASSWORD=change-me-in-production
# First-run admin bootstrap (Docker entrypoint reads OCTOP_DEFAULT_PASSWORD)
OCTOP_ADMIN_USERNAME=admin
OCTOP_DEFAULT_PASSWORD=change-me-in-production
# Timezone and logging
OCTOP_DEFAULT_TIMEZONE=America/New_York
OCTOP_LOG_LEVEL=infoservices:
octop:
image: octop:latest
env_file: .env
environment:
- OCTOP_ADMIN_USERNAME
- OCTOP_DEFAULT_PASSWORD
- OCTOP_DATABASE_DRIVER
- OCTOP_DATABASE_HOST
- OCTOP_DATABASE_PORT
- OCTOP_DATABASE_NAME
- OCTOP_DATABASE_USER
- OCTOP_DATABASE_PASSWORD
ports:
- "${OCTOP_PORT:-8088}:8088"
volumes:
- octop_data:/root/.octopFor Docker Compose, put OCTOP_DATABASE_* in docker/.env and list those keys under environment: in docker-compose.yml. Compose uses .env for interpolation only; unset keys do not enter the container. Writing the same keys to the mounted ~/.octop/env also works.
Never store OCTOP_DATABASE_PASSWORD, OCTOP_ADMIN_PASSWORD, or OCTOP_DEFAULT_PASSWORD directly in config.json for production deployments. Keep them in environment variables or a secrets manager, and ensure your .env file is excluded from version control (add it to .gitignore). Restrict config.json file permissions to the service account only (chmod 600 ~/.octop/config.json).

