Backups and operations

Back up and restore, reset history, recover a damaged database, manage access tokens, repair provider sign-ins, and understand gateway access rules.

This page is for whoever runs the Oktapod machine. For everyday fixes, start with Troubleshooting.

#Backups

Take a backup before any repair, restore, reset, or manual storage work:

oktapod backup --output oktapod-backup.tgz

A backup contains your settings (oktapod.json) and Oktapod's managed data. It holds the same private data as Oktapod itself, so store it accordingly. Settings snapshots are hash-checked and restored with owner-only permissions. Managed provider credential file references are rebased to the restored data directory. Environment keys and external secret-manager values are excluded. The legacy env block remains machine-local and is preserved during restore. Managed storage includes the primary and governance databases, the registered memory shard generation, media and voice files, runtime artifacts, and learned procedure packages. Database snapshots use VACUUM INTO; the complete shard catalog, file hashes, row counts, and SQLite integrity are checked before restore. Live execution-pool workspaces, toolchains, logs, reports, and previous backups are excluded. Managed symlinks are rejected; external import roots stay external. Older backups without a settings snapshot preserve the current settings.

Updates also take a full backup automatically before they change anything, and restore it if the update fails. See Updates.

#Restore

oktapod restore --input oktapod-backup.tgz --verify
oktapod checkup

Restoring into a separate --data-dir writes recovered settings under that directory's .oktapod/oktapod.json. It leaves the live runtime and its settings running unchanged; starting the recovered copy is a separate operation.

Restore never overwrites your current data in place. It first moves it aside into a restore snapshot, then unpacks the backup. To inspect a restore before Oktapod starts again, add --no-start, then run oktapod start when ready.

Restore snapshots can be large. The newest three are kept; older ones are pruned after a successful restore. Manage them explicitly with:

oktapod restore --snapshots
oktapod restore --prune-snapshots --dry-run
oktapod restore --prune-snapshots

A failed restore or failed verification never prunes anything.

#Reset history but keep setup

Reset clears history, such as conversations, runs, approvals, memory, and records, while keeping your setup and connections:

oktapod reset-instance --dry-run
oktapod stop
oktapod reset-instance --confirm RESET
oktapod start
oktapod checkup

The dry run checks the reset on a temporary copy without touching your data. The real reset archives the previous databases first. It is not a substitute for restoring a specific backup.

#Update rollback archives

Each update that changes something keeps a rollback archive. The newest three are kept automatically after a verified update; a failed update keeps its archive for recovery.

oktapod update --backups
oktapod update --prune-backups --dry-run
oktapod update --rollback <tag>

Do not delete files under ~/.oktapod by hand to free space during an outage. Use the dry-run commands to see what can be reclaimed first.

#Recover a damaged database

If health checks report database disk image is malformed, do not keep restarting. Recover into a separate file, check it, then swap it in:

sqlite3 ~/.oktapod/data/core.db '.recover' > /tmp/oktapod-core-recover.sql
sqlite3 /tmp/oktapod-core-recovered.db < /tmp/oktapod-core-recover.sql
sqlite3 /tmp/oktapod-core-recovered.db 'PRAGMA integrity_check;'
oktapod recover-core-db --candidate /tmp/oktapod-core-recovered.db --dry-run
oktapod recover-core-db --candidate /tmp/oktapod-core-recovered.db
oktapod up
oktapod checkup

The path above is the default data folder. recover-core-db refuses a candidate that fails the integrity check, and keeps the old database. Treat the recovered files as private: they contain your data.

#Access tokens

The web app uses a private access key. Scripts and other clients can use gateway tokens instead. A new or rotated token's value is shown once:

oktapod token list
oktapod token create --name ops-laptop --purpose gateway.client --role operator
oktapod token rotate --name ops-laptop
oktapod token revoke --name ops-laptop

Store the value in a password manager or secret store, never in chat, tickets, or committed files. --help on any token command only prints usage; it never issues a token.

#Provider sign-in recovery

#Expiry / Re-auth

If an AI provider or app sign-in expires, or token refresh starts failing, sign in again. Re-run oktapod auth login --provider <provider>, then confirm:

oktapod auth login --provider <provider>
oktapod auth status
oktapod checkup

#Revocation

To stop Oktapod using a sign-in, for example after a credential incident:

oktapod auth logout --provider <provider>
oktapod auth status

Also revoke the credential with the provider when it must stop working everywhere.

#Billing / Entitlement

If sign-in is healthy but requests still fail, check the provider's billing, subscription, tenant consent, or model access before replacing a working credential. Then run:

oktapod auth status
oktapod checkup

#Gateway access rules

• Protected routes need a real identity even on the same machine: the access key, an issued client token, or a trusted Tailscale session. Role and scope headers sent by a caller are not trusted on their own.
• Oktapod refuses to listen on a non-local address unless client credentials are configured or it uses the Tailscale path. Prefer loopback or Tailscale Serve; see Private web access.
• Writes need an operator or admin role plus the right scope, and are rate limited. Reading memory, status, and the current brief are reads; correcting memory, refreshing the brief, and changing node capabilities are writes.
• Passing the gateway is not enough to act. Every action still goes through policy and approvals.
• A webhook proves which bridge sent it, not who the payload claims to be.

#Monitoring for a support session

Oktapod exports no telemetry by default. For an agreed debugging session, set OKTAPOD_OBSERVABILITY_ENABLED=true in the service environment together with a collector or error-tracking address you approve, then restart. Remove both and restart again when the session ends. See Privacy and your data.

#Fleet-managed hosts

Oktapod runs standalone by default. Organizations using the separate Oktapod Fleet control plane can install its connector package on a Linux host that already runs Oktapod. The package adds oktapod-fleet-agent.service, which supplies approved desired state, health probes, and update intent. The local Oktapod still owns execution, policy, memory, connectors, and applying updates.

sh preflight.sh
sudo sh install.sh
sudo systemctl status oktapod-fleet-agent.service --no-pager

Run the package's preflight.sh again before any repair.