Octop Environment Variables: Complete Config Reference

Override any Octop config.json field with an environment variable. Ideal for Docker, CI pipelines, and keeping secrets off the filesystem.

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_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	Octop123	Docker / image first-boot admin password. Written to /data/.octop/credential.txt. 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

# 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
OCTOP_ADMIN_USERNAME=admin
OCTOP_ADMIN_PASSWORD=change-me-in-production

# Timezone and logging
OCTOP_DEFAULT_TIMEZONE=America/New_York
OCTOP_LOG_LEVEL=info

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.

Never store OCTOP_DATABASE_PASSWORD or OCTOP_ADMIN_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).