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`	bool	`false`	Enable segmented history archive for the next completed turn.
`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.

Docker `.env` example

Create a .env file next to your docker-compose.yml and populate the variables relevant to your deployment:

.env

docker-compose.yml (snippet)

.env

# 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=info

docker-compose.yml (snippet)

services:
  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/.octop

NOTE

For 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.

WARNING

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).

Octop Environment Variables: Complete Config Reference#

#Variable reference

#Docker .env example

Octop Environment Variables: Complete Config Reference

Variable reference

Docker `.env` example