> For AI agents: the complete documentation index is available at /en/llms.txt, the full documentation bundle is available at /en/llms-full.txt.

# 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](/en/guide/guides/private-market.md).                                                                                   |
| `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](/en/guide/guides/private-market.md).                                                                                                                |
| `SKILL_MARKET_ORIGIN`                  | origin        | `https://api.skillhub.cn`      | Skill search, rankings, and ZIP download. Scheme, host, and port only. See [Skill market](/en/guide/guides/skill-market.md).                                                                                                                                      |
| `SKILLSET_ORIGIN`                      | origin        | `https://api.skillhub.cn`      | Skillset detail used by **Import from skill market**. Scheme, host, and port only. See [Skill market](/en/guide/guides/skill-market.md).                                                                                                                          |
| `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:


```bash .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
```
```yaml 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`).
> 

