Get started / Configuration

Configuration

Where AgentParley keeps its state, and the knobs you'll actually reach for.

The home directory

One directory holds an entire instance. It's resolved in this order: a --home flag, the PARLEY_HOME environment variable, then the default ~/parley.

~/parley/text

parley.yaml        # the config file (this page)
data/              # SQLite database, vault, plugin data
plugins/           # external plugin DLLs (see Installing plugins)
agents/            # per-agent soul, instructions, cron.yml, settings
workspaces/        # per-agent working directories
sessions/          # durable session state
shared/            # the shared wiki
logs/

parley.yaml

Most settings are edited through the console (Settings), but they all live in parley.yaml and can be edited directly. The shape:

~/parley/parley.yamlyaml

server:
  apiToken: ap_live_...      # admin scope (managed via 'token rotate')
  readToken: ap_read_...     # read-only scope
  port: 8420

session:
  compactAtPercent: 80       # compact when context passes this % of the window
  keepRecentTokens: 20000    # recent conversation kept verbatim on compaction
  parkTtlHours: 24           # how long a parked session waits before timeout
  budget:                    # per-agent spend caps (see Security)
    default: { usd: 25, action: warn }

providerSelections:          # which selectable provider is active per group
  websearch: brave

models:                      # the model catalog (added in the console)
  - name: claude-opus
    provider: anthropic
    model: claude-opus-4-8
    capabilities: { context: 200000 }

plugins:
  loadOrder: [base, telegram, brave]   # topological; 'base' is always first

Access tokens

Two scopes guard the API and console: admin (full control) and read (observers watch sessions but hold no keys). Rotate them any time:

bash

dotnet run --project src/AgentParley.Cli -- token rotate          # admin
dotnet run --project src/AgentParley.Cli -- token rotate --read   # read-only

Tokens never leave the server in a readable form, and secret values (model keys, bot tokens) live in the encrypted vault — never in parley.yaml and never in a model's context. See Security.

Secrets

Raw vault secrets (used, for example, by a channel's secretRefs) are managed with the CLI:

bash

dotnet run --project src/AgentParley.Cli -- secret set telegram-token   # prompts, hidden input
dotnet run --project src/AgentParley.Cli -- secret list
dotnet run --project src/AgentParley.Cli -- secret rm telegram-token

Provider and plugin API keys are usually set through their Settings panel in the console instead — a plugin declares the fields it needs and the value is written straight to the vault. See Providers.

Environment summary

Variable / flag	Purpose
`PARLEY_HOME`	Override the home directory for this process.
`--home <path>`	Same, per CLI invocation. Takes precedence over the env var.
`--port <n>`	Override the serve port (default 8420).

← Previous

The console

Security