Data and file locations

xopc keeps its machine-local state under one directory and gives each Agent a separate working folder. Knowing the difference makes backup, privacy review, and troubleshooting much easier.

Default locations

The default state directory is ~/.xopc/.

Path	Contains	Handle as
~/.xopc/xopc.json	Main configuration	Private; may reference credentials and network settings
~/.xopc/xopc.db	Sessions, notes and note history, Workflows, queues, sharing records, user context, Automations, and other local records	Private and important to back up
~/.xopc/credentials/	API, OAuth, channel, and pairing credentials	Secret
~/.xopc/agents/<id>/profile/	Agent identity and instruction Markdown	User-editable, usually private
~/.xopc/workspace/<id>/	Files and artifacts used by an Agent	User data
~/.xopc/skills/	Installed Skills	Review before trusting
~/.xopc/extensions/	Installed extensions	Review before trusting
~/.xopc/logs/	Runtime and diagnostic logs	May contain private metadata
~/.xopc/tools/	Managed Node.js and Python runtimes	Re-creatable cache/runtime data

An Agent can be configured with a different workspace path, so use its editor or xopc config show before assuming the default.

State, Agent profile, and workspace

• State is xopc's local database, configuration, credentials, logs, and installed capabilities.
• Agent profile describes who an Agent is and how it should behave.
• Workspace contains the files that an Agent reads and creates while doing work.

Do not store model keys in the workspace. Do not treat workspace Markdown as a replacement for the local Session database.

Find the active paths

xopc profile list
xopc config path
xopc config show

Profiles may use directories such as ~/.xopc-work. Environment variables and command-line options can also override paths.

Back up

For an encrypted offline state-directory backup, follow Back up and restore xopc:

xopc backup create --output /secure/xopc-backup --passphrase-file /secure/passphrase
xopc backup verify /secure/xopc-backup --passphrase-file /secure/passphrase

Stop the Gateway first. This command covers the active state directory and refuses known external workspace, config, or credential paths. It does not yet perform automatic cloud migration.

For a manual backup that also includes external paths:

1. stop or pause active Agent runs and Automations;
2. stop the Gateway service;
3. copy the active state directory to encrypted storage;
4. separately include any Agent workspace located outside that directory;
5. restart the Gateway and verify health.

The backup contains credentials and private conversations. Encrypt it, restrict access, and define a retention period.

Before restoring, keep a copy of the current state, use a compatible xopc version, and make sure file ownership is correct. Do not merge SQLite files manually.

SQLite is the authority for structured application state, including Workflow events, note versions, message queues, share records, extension UI storage and channel cursors. Attachments, share artifacts, Agent profiles and workspaces remain files. A database-only backup is not a complete recovery set. Client-local unsent drafts and offline operations are not included in Gateway backups.

Run the Gateway and its SQLite database on the same host with local persistent storage. A NAS can host the Gateway or receive backup artifacts; do not open the live database through SMB/NFS. Keep the database and file assets in the same backup set so ownership, transaction, and recovery boundaries remain intact.

Safe manual editing

It is normally safe to edit Agent profile Markdown and ordinary workspace files. Use xopc commands or the UI for configuration, credentials, Sessions, Automations, Skills, and extensions.

Avoid manually editing xopc.db, lock files, credential stores, or files under managed runtime directories.

Move or isolate state

Use xopc profile commands for reusable separate environments. Advanced path overrides include XOPC_STATE_DIR, XOPC_CONFIG_PATH, XOPC_WORKSPACE, XOPC_CREDENTIALS_DIR, and XOPC_LOG_DIR.

When using a system service or container, set absolute paths and confirm the service account can read and write them.