Data and credentials

Workspace layout on disk

Your workspace is a directory of plain files organized under a git-like history. The root contains desk.toml; subdirectories hold structured data. You own every file — back them up, version them, or inspect them with any text tool.

Workspace directory reference

Credentials and the secret store

API keys and auth tokens are never written into desk.toml. They are referenced by environment variable name ({ env = "EQ_API_KEY" }) or by a path in a secret store. At startup, Qoc resolves references and holds credentials in memory; they are not logged or persisted to disk in plaintext.

Supported secret sources in V0.73.0: environment variables, Docker secrets, and files on a tmpfs mount. A plugin interface for external secret managers is on the roadmap.

Referencing secrets in desk.toml

# 1. Environment variable (simplest)
[connector.auth]
api_key = { env = "EQ_API_KEY" }

# 2. Docker secret file
[connector.auth]
api_key = { file = "/run/secrets/eq_api_key" }

# 3. Inline file path (use tmpfs for sensitive hosts)
[connector.auth]
api_key = { file = "/dev/shm/eq_api_key.txt" }

Encryption at rest

Qoc encrypts the orders/ and snapshots/ directories at rest using AES-256-GCM with a key derived from your auth token. If the auth token is rotated, Qoc re-encrypts existing data before completing the rotation.

The qoc_state Docker volume (connector session state) is also encrypted. Plain workspace files (desk.toml, research/, issues/) are not encrypted — they contain no secrets and benefit from being readable by standard tools.

Backing up your workspace

1. 1

   Stop or pause the agent

   Run qoc run pause to stop the agent loop without stopping the container. This prevents concurrent writes during the backup.

2. 2

   Archive the workspace directory

   Copy the entire workspace directory to your backup destination. Include the .git directory if present — it contains the full workspace history.

3. 3

   Back up the auth token separately

   Store the auth token in a separate, secure location from the workspace. Without it you cannot decrypt orders/ or snapshots/ from a backup.

4. 4

   Resume the agent

   Run qoc run resume to restart the agent loop. Qoc will reconcile positions with connected venues and resume normal operation.

Related topics