• English

      • 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

      FieldTypeDefaultDescription
      bind_hoststring127.0.0.1Interface Octop listens on. Set to 0.0.0.0 to accept connections from other machines on your network.
      portint8088TCP port Octop binds to.
      log_levelstringinfoLog verbosity. One of debug, info, warning, or error.
      access_token_ttl_secondsint86400How long a JWT access token stays valid (in seconds). The default is 24 hours.
      login_max_attemptsint5Number of failed login attempts allowed before an account is locked out.
      login_lockout_secondsint900How long (in seconds) an account stays locked after hitting login_max_attempts. The default is 15 minutes.
      cors_originslist[]List of origins permitted to make cross-origin requests to the API. Leave empty to disallow all cross-origin requests.
      default_timezonestringAsia/ShanghaiIANA timezone used for dashboard timestamps, cron scheduling, and the agent harness.
      enable_dashboardbooltrueServe the built-in React dashboard at /. Set to false to expose the API only.
      enable_api_docsboolfalseExpose the interactive Scalar API docs at /api/docs. Safe to enable during development; keep off in production.
      require_setup_passwordbooltrueRequire 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_mbint100Maximum 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_enabledboolfalseOptional 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_minutesint30Idle 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

      FieldTypeDefaultDescription
      driverstringsqliteStorage backend. Set to sqlite or postgresql.
      sqlite_pathstringoctop.dbPath to the SQLite database file. Relative paths resolve from ~/.octop/.
      hoststring127.0.0.1PostgreSQL server host. Used only when driver is postgresql.
      portint5432PostgreSQL server port.
      databasestringoctopPostgreSQL database name.
      userstringoctopPostgreSQL user.
      passwordstring""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

      FieldTypeDefaultDescription
      enabledboolfalseEnable TLS termination inside Octop.
      cert_filestring""Absolute path to the PEM-encoded certificate file.
      key_filestring""Absolute path to the PEM-encoded private key file.

      See TLS & Service for the full walk-through, including self-signed certificate generation.

      backup section

      FieldTypeDefaultDescription
      auto_enabledboolfalseEnable automatic system backups inside octop run.
      schedulestringcron:0 4 * * *Cron or interval:<seconds> in the server timezone.
      retention_countint7How many octop-auto-backup-* archives to keep. Manual octop-backup-* files are never pruned.
      include_configbooltrueInclude config.json and env in new archives.
      include_workspacesbooltrueInclude agent workspaces.
      include_skill_packagesbooltrueInclude global skill packages.
      include_pluginsbooltrueInclude installed plugins.
      include_knowledgebooltrueInclude knowledge-base files.
      include_chatsboolfalseInclude 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.

      Example config.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.