> ## 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 config.json Reference: All Server Configuration Fields

> Octop reads ~/.octop/config.json for server settings. Configure the port, CORS, timezone, database backend, and TLS from this file.

Octop generates `config.json` inside `~/.octop/` on its first run. You can edit the file directly at any time to change server behavior — no reinstall needed. Environment variables always take priority over file values, so any `OCTOP_*` variable you export will override the corresponding key in this file.

## Field reference

### Core settings

| Field | Type | Default | Description |
| - | - | - | - |
| `bind_host` | string | `127.0.0.1` | Interface Octop listens on. Set to `0.0.0.0` to accept connections from other machines on your network. |
| `port` | int | `8088` | TCP port Octop binds to. |
| `log_level` | string | `info` | Log verbosity. One of `debug`, `info`, `warning`, or `error`. |
| `access_token_ttl_seconds` | int | `86400` | How long a JWT access token stays valid (in seconds). The default is 24 hours. |
| `login_max_attempts` | int | `5` | Number of failed login attempts allowed before an account is locked out. |
| `login_lockout_seconds` | int | `900` | How long (in seconds) an account stays locked after hitting `login_max_attempts`. The default is 15 minutes. |
| `cors_origins` | list | `[]` | List of origins permitted to make cross-origin requests to the API. Leave empty to disallow all cross-origin requests. |
| `default_timezone` | string | `Asia/Shanghai` | IANA timezone used for dashboard timestamps, cron scheduling, and the agent harness. |
| `enable_dashboard` | bool | `true` | Serve the built-in React dashboard at `/`. Set to `false` to expose the API only. |
| `enable_api_docs` | bool | `false` | Expose the interactive Scalar API docs at `/api/docs`. Safe to enable during development; keep off in production. |
| `require_setup_password` | bool | `true` | Require a password gate during the first-run setup wizard. Set to `false` only for fully unattended bootstraps using `OCTOP_ADMIN_USERNAME` and `OCTOP_ADMIN_PASSWORD`. |
| `max_upload_mb` | int | `100` | Maximum upload size in MiB for chat attachments, IM inbound files, and knowledge documents. Values below `1` fall back to `100`; values above `1024` are capped at `1024`. |
| `history_v2_enabled` | bool | `false` | Optional segmented history archive. When `true`, the next completed turn writes the new format. Existing new-format rows stay readable if you turn it off. Override with `OCTOP_HISTORY_V2_ENABLED`. |
| `browser_idle_timeout_minutes` | int | `30` | Idle minutes before Octop reaps a local Chrome started from the workbench. Login cookies stay on disk. Override with `OCTOP_BROWSER_IDLE_TIMEOUT_MINUTES`. |

### `database` section

| Field | Type | Default | Description |
| - | - | - | - |
| `driver` | string | `sqlite` | Storage backend. Set to `sqlite` or `postgresql`. |
| `sqlite_path` | string | `octop.db` | Path to the SQLite database file. Relative paths resolve from `~/.octop/`. |
| `host` | string | `127.0.0.1` | PostgreSQL server host. Used only when `driver` is `postgresql`. |
| `port` | int | `5432` | PostgreSQL server port. |
| `database` | string | `octop` | PostgreSQL database name. |
| `user` | string | `octop` | PostgreSQL user. |
| `password` | string | `""` | PostgreSQL password. In production, prefer the `OCTOP_DATABASE_PASSWORD` environment variable over storing the password here. |

> [!WARNING]
>
> Avoid storing the PostgreSQL password in `config.json` in production — use the `OCTOP_DATABASE_PASSWORD` environment variable instead, and restrict the file's permissions to your service account.

### `tls` section

| Field | Type | Default | Description |
| - | - | - | - |
| `enabled` | bool | `false` | Enable TLS termination inside Octop. |
| `cert_file` | string | `""` | Absolute path to the PEM-encoded certificate file. |
| `key_file` | string | `""` | Absolute path to the PEM-encoded private key file. |

See [TLS & Service](https://octop.mintlify.site/configuration/tls-service.md) for the full walk-through, including self-signed certificate generation.

### `backup` section

| Field | Type | Default | Description |
| - | - | - | - |
| `auto_enabled` | bool | `false` | Enable automatic system backups inside `octop run`. |
| `schedule` | string | `cron:0 4 * * *` | Cron or `interval:<seconds>` in the server timezone. |
| `retention_count` | int | `7` | How many `octop-auto-backup-*` archives to keep. Manual `octop-backup-*` files are never pruned. |
| `include_config` | bool | `true` | Include `config.json` and env in new archives. |
| `include_workspaces` | bool | `true` | Include agent workspaces. |
| `include_skill_packages` | bool | `true` | Include global skill packages. |
| `include_plugins` | bool | `true` | Include installed plugins. |
| `include_knowledge` | bool | `true` | Include knowledge-base files. |
| `include_chats` | bool | `false` | Include chat history and trajectories. Off by default because archives can grow quickly. |

Override with `OCTOP_BACKUP_AUTO_ENABLED`, `OCTOP_BACKUP_SCHEDULE`, `OCTOP_BACKUP_RETENTION_COUNT`, and `OCTOP_BACKUP_INCLUDE_*`. See [Backup & Restore](https://octop.mintlify.site/guides/backup-restore.md).

## Example config.json

```json theme={null}
{
  "bind_host": "0.0.0.0",
  "port": 8088,
  "log_level": "info",
  "access_token_ttl_seconds": 86400,
  "login_max_attempts": 5,
  "login_lockout_seconds": 900,
  "cors_origins": ["https://app.example.com"],
  "default_timezone": "America/New_York",
  "enable_dashboard": true,
  "enable_api_docs": false,
  "require_setup_password": true,
  "max_upload_mb": 100,
  "backup": {
    "auto_enabled": false,
    "schedule": "cron:0 4 * * *",
    "retention_count": 7
  },
  "database": {
    "driver": "postgresql",
    "host": "127.0.0.1",
    "port": 5432,
    "database": "octop",
    "user": "octop"
  },
  "tls": {
    "enabled": true,
    "cert_file": "/etc/ssl/octop/cert.pem",
    "key_file": "/etc/ssl/octop/key.pem"
  }
}
```

> [!TIP]
>
> Set `"enable_api_docs": true` to unlock the interactive Scalar API explorer at `/api/docs`. It lets you browse every endpoint, inspect request/response schemas, and send test requests directly from your browser — ideal when building integrations or writing automation scripts.

> [!NOTE]
>
> Configuration changes in `config.json` take effect the next time you restart the server. Run `octop service restart` if Octop is running as a system service, or stop and re-run `octop run` for foreground mode.


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