> ## Documentation Index
> Fetch the complete documentation index at: https://octop.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash .env theme={null}
# 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
```

```yaml docker-compose.yml (snippet) theme={null}
services:
  octop:
    image: octop:latest
    env_file: .env
    environment:
      - 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` 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`).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.