Octop Data Directory: Files and Folders in ~/.octop/

Everything Octop stores — database, agent workspaces, secrets, logs, and plugins — lives under ~/.octop/. Learn what each file and folder does.

Octop is local-first: every file it needs — database, secrets, agent workspaces, plugins, logs, and SSL certificates — lives under ~/.octop/ (or whatever path you set with OCTOP_HOME). The directory and its default contents are created automatically on the first run.

​

Directory layout

~/.octop/
├── config.json           — server settings (port, CORS, timezone, DB, TLS)
├── env                   — optional dotenv (OCTOP_DATABASE_*, API keys, …); loaded at server start
├── octop.db              — SQLite: users, agents, providers, sessions, audit log
├── cli_state.json        — CLI defaults (base URL, pinned user/agent)
├── repl_history          — readline history for `octop chats repl`
├── octop.log             — default foreground log output
├── secrets/
│   └── jwt_secret        — auto-generated 32-byte key; rotate with octop admin rotate-jwt-secret
├── agents/<agent_id>/    — per-agent workspace: LangGraph state, skills, attachments
├── plugins/              — installed third-party plugins
├── backups/              — manual and automatic backup archives
├── embedding_models/     — local ONNX embedding cache
├── published_experts/    — published expert snapshots
├── ssl/                  — self-signed certs generated by octop run --ssl
└── logs/                 — rotating service logs plus harness runtime diagnostics (`[agent=…]`)

env is dotenv format and is applied before config.json loads. Use it when process environment is hard to set (for example a Docker volume) without editing Compose. The web UI Environments page and some tools also read and write this file.

config.json

Human-editable server settings. Edit directly and restart to apply changes. See Config File for the full field reference.

octop.db

SQLite database holding all control-plane data — users, agents, providers, sessions, and audit records.

secrets/

Auto-generated cryptographic material. Do not edit manually. Rotate with the octop admin command.

agents/

One subdirectory per agent, containing that agent’s LangGraph checkpoint state, uploaded attachments, and skill configs.

​

Rotate the JWT secret

Octop generates ~/.octop/secrets/jwt_secret on first start and uses it to sign every access token. Rotate it with:

octop admin rotate-jwt-secret

Rotating the JWT secret immediately invalidates every active login session across all users. Everyone will be signed out and must log in again. Plan the rotation for a low-activity window and notify your users in advance.

​

Move the data directory

Set OCTOP_HOME to any absolute path to store all Octop data elsewhere — useful for mounting a dedicated volume or placing data on faster storage:

export OCTOP_HOME=/mnt/data/octop
octop run

Octop creates the directory and populates it on first run. To migrate an existing installation, stop the server, copy ~/.octop/ to the new path, then set OCTOP_HOME before restarting.

For persistent overrides, add the export OCTOP_HOME=… line to your shell profile (e.g. ~/.bashrc or ~/.zshrc), or set it in the environment block of your systemd unit or launchd plist.

​

Back up and restore

Everything Octop needs is in ~/.octop/, which makes backups straightforward. Use octop backup create / octop backup restore — see Backup commands.

Schedule regular backups so you always have a recent snapshot. The archive includes config.json, the SQLite database, cli_state.json, secrets, agent workspaces, and installed plugins — everything required to restore a fully working instance on a fresh machine.