Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.getpioneer.dev/llms.txt

Use this file to discover all available pages before exploring further.

Pioneer stores runtime secret values in a local SQLite keystore file named keystore.db. For the gateway, the file lives under the gateway runtime home next to gateway.db. Run pioneer status to see the runtime home path for the current installation.

​
What Goes In The Keystore

The keystore stores secret values that should not be written into ordinary config or domain tables:
Secret kindStored value
Provider API keyAPI keys and tokens used by gateway provider adapters
MCP secretSecret env values, HTTP headers, tokens, and authorization values from MCP install config
Superuser JWT materialSigning material for the current singleton superuser bearer token flow
Desktop gateway auth tokenBearer tokens saved by the desktop app for gateway connections
User JWT tokenReserved namespace for future non-superuser token support
The current implemented JWT flow has one superuser signing material entry. Future user tokens are separate from the superuser namespace.

​
What Does Not Store Raw Secrets

gateway-settings.toml is intentionally small: 
[secrets]
backend = "keystore"
It does not contain a jwt_secret, provider key tables, or MCP secret tables. gateway.db stores normal gateway domain state. For MCP, it stores installation rows, catalog snapshots, audit data, redacted transport/source data, and secret refs. It does not store raw MCP secret values. The desktop gateway registry stores auth_token_ref values for gateway endpoints. It rejects the old raw auth_token field.

​
Security Model

Current keystore storage is not encrypted at rest. Pioneer opens db-keystore with encryption disabled. Pioneer does harden filesystem permissions for the runtime directory and keystore SQLite files, including keystore.db, keystore.db-wal, and keystore.db-shm when present. This limits normal access to the OS user that owns the gateway or desktop runtime. That is not the same as encryption. Any OS user, administrator, backup process, malware, or service account that can read the runtime home can read keystore.db. Encrypting keystore contents is planned as a separate task.

​
Maintenance Commands

Inspect keystore status without printing secret values: 
pioneer secrets status
pioneer secrets status --json
The report includes the storage path, encryption mode, counts by secret kind, permission health, and MCP orphan status. If gateway.db does not exist yet, MCP orphan status is reported as unavailable. Clean orphan MCP secret values: 
pioneer secrets garbage-collection --dry-run
pioneer secrets garbage-collection
pioneer secrets garbage-collection --json
Garbage collection only applies to MCP secret values whose refs are no longer present in gateway.db. It does not delete provider keys, desktop gateway tokens, or JWT material. The command refuses to run when gateway.db is missing. Rotate the singleton superuser JWT signing material: 
pioneer secrets rotate-jwt-token superuser
pioneer secrets rotate-jwt-token superuser --json
Rotation does not print token material. If signing material already existed, existing superuser bearer tokens become invalid. Issue a new bearer token after rotation: 
pioneer issue-superuser-token