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

> [card] config.json
>
> Human-editable server settings. Edit directly and restart to apply changes. See [Config File](https://octop.mintlify.site/configuration/config-file.md) for the full field reference.

> [card] octop.db
>
> SQLite database holding all control-plane data — users, agents, providers, sessions, and audit records.

> [card] secrets/
>
> Auto-generated cryptographic material. Do not edit manually. Rotate with the `octop admin` command.

> [card] 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:

```bash theme={null}
octop admin rotate-jwt-secret
```

> [!WARNING]
>
> 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:

```bash theme={null}
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.

> [!NOTE]
>
> 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](https://octop.mintlify.site/cli/channel-cron-commands.md#octop-backup).

> [!TIP]
>
> 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.


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