Configuration

Configuration

Server environment variables

Variable	Default	Description
BIND_ADDR	0.0.0.0:3000	HTTP bind address
POSTGRES_URL	""	PostgreSQL connection URL
OBJECT_STORE_ROOT	/tmp/frameshift-objects	Filesystem object store root
LOG_LEVEL	info	Log filter (trace, debug, info, warn, error)
LOG_FORMAT	text	Log format: text or json
MAX_REQUEST_BYTES	1048576	Maximum request body size (1 MB default)
MAX_SEARCH_LIMIT	200	Maximum limit parameter on search endpoints
SHUTDOWN_GRACE	30	Graceful shutdown timeout in seconds

XDG directories

Frameshift follows the XDG Base Directory Specification:

Purpose	Variable	Default
Persona cache and project state	$XDG_DATA_HOME/frameshift/	~/.local/share/frameshift/

Project state layout

$XDG_DATA_HOME/frameshift/
  cache/<sha256>/                              # Content-addressed pack cache
  projects/<project-id>/
    config.toml                                # Declared dependencies
    lock.toml                                  # Installed versions, hashes, pubkeys
    active                                     # Currently active persona name
    personas/<name>/
      source/                                  # Pack contents
      rendered/{claude,codex,gemini,generic}/   # Per-agent rendered output
      growth.jsonl                             # Structured growth log
    orchestrator/                              # Automate mode state

Vault

The vault stores identity, authentication, memory configuration, and preferences. It is encrypted at rest using age with scrypt passphrase recipients.

Vault location: $XDG_DATA_HOME/frameshift/vault.age

The vault TOML schema supports:

• Identity: Email, handle
• Auth: API keys, tokens for marketplace access
• Memory config: Endpoint URL, authentication for memory backends
• Preferences: Runtime mode, arbitrary key-value variables
• Overlay prose: Per-host text blocks injected during rendering

Daemon

The daemon listens on a Unix domain socket for JSON-RPC 2.0 IPC. It watches the project directory for file changes and triggers orchestrator evaluation when automate mode is enabled.

Object store backends

Filesystem (default)

OBJECT_STORE_ROOT=/path/to/store

Objects are stored in a sharded directory tree: {root}/{aa}/{bb}/{64-char-hex-hash}.

Cloudflare R2

The frameshift-objects-r2 crate provides an S3-compatible backend for Cloudflare R2. Configuration via standard AWS SDK environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_ENDPOINT_URL).

Database

The marketplace catalog uses PostgreSQL via diesel-async with bb8 connection pooling. Migrations are embedded and run automatically on startup.

POSTGRES_URL=postgres://user:pass@host:5432/frameshift