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

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.


> **WARNING**
> 
> A corrupt `config.json` is a hard error. Octop names the path and parser position, then refuses to start or rewrite the file. It never treats a broken file as empty — that used to wipe other settings (for example a PostgreSQL `database` section) and silently fall back to SQLite. Fix the JSON and retry.
> 


## 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`           | —      | ignored         | Retired. Octop ignores this key and `OCTOP_HISTORY_V2_ENABLED`. On startup it migrates an existing `history_v2.sqlite` back into the original history tables.              |
| `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.
> 


When `driver` is `postgresql`, skill-package files and knowledge-base originals are stored in that database, and knowledge vectors use pgvector. SQLite keeps them in local directories. Enable the `vector` extension before you index knowledge. This release does not migrate existing SQLite content into PostgreSQL. Choose the driver at install time.

### `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](/en/guide/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](/en/guide/guides/backup-restore.md).

## Example config.json

```json
{
  "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.
> 

