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.

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

​

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"
  }
}

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.

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.