Guides
Page 2 of 6
Configuration
Where Charon keeps its files, every setting in charon.toml, and how it finds cloud keys.
You rarely need to edit files: the app’s Settings, Backends and Policies screens change the same settings. This page is for when you want the files themselves.
Files
| Path | Holds |
|---|---|
~/.config/charon/charon.toml |
Settings and backends |
~/.config/charon/policy.yaml |
Budgets, aliases and rules (policies) |
~/.config/charon/admin.token |
The password for the /admin API |
~/.config/charon/credentials |
Optional cloud keys (must be readable only by you) |
~/.local/share/charon/ |
charon.db (request log, spend, client keys), logs/, models/ |
XDG_CONFIG_HOME and XDG_DATA_HOME move these if set. After editing, run charon reload. A file with
a mistake is rejected with its line and column, and the old settings stay in place.
charon.toml
Every key is optional. These are the defaults:
[server]
host = "127.0.0.1" # other addresses need allow_remote
port = 7777
allow_remote = false # let other computers connect (needs TLS and a client key)
tls_cert = "" # certificate and key files for HTTPS
tls_key = ""
allow_anonymous_local = true # apps on this machine may call /v1 without a key
max_body_mb = 32
per_client_concurrency = 32 # requests one client may have running at once
max_concurrent_requests = 256 # requests running at once across all clients
max_connections = 1024 # open connections; more are refused until some close
threads = 0 # 0 = one per CPU core, up to 4
cors_origins = ["tauri://localhost", "http://tauri.localhost", "http://localhost:1420"]
[logging]
level = "info" # trace | debug | info | warn | error
log_bodies = false # save prompts and replies in the request log
request_log_max_rows = 100000 # older log rows are deleted
[models]
dir = "" # "" = ~/.local/share/charon/models
idle_unload_minutes = 15 # 0 = keep models loaded
vram_reserve_mb = 1280 # GPU memory kept free on discrete GPUs
allow_partial_offload = true # run part of a model on the CPU if it doesn't fit on the GPU
worker_path = "" # "" = charon-worker next to charond
[routing]
pause_cloud = false # never use a cloud ("Pause cloud" in the app)
force_local_only = false # treat every request as local-only ("Local-only mode")Backends are [[backends]] tables; see Backends.
Sharing a Mac with other people? Set allow_anonymous_local = false and give each app a key
from the Keys page. Otherwise anyone logged in to the same Mac can send requests, including ones that
go to your cloud.
charon settings key=value changes port, log_level, log_bodies, pause_cloud,
force_local_only, allow_anonymous_local, idle_unload_minutes and vram_reserve_mb without
editing the file.
Cloud keys
Keys never go in charon.toml. Charon looks for a backend’s key in this order:
- Environment variable:
key_envif set, elseBEDROCK_API_KEYorAWS_BEARER_TOKEN_BEDROCK(Bedrock),AZURE_OPENAI_API_KEY(Azure),CLOUDSDK_AUTH_ACCESS_TOKEN(Vertex AI), orOPENAI_API_KEY(api.openai.comonly). - macOS Keychain:
key_ref = "keychain:<account>", servicecharon. The app and--key-from-keychainsave keys here. - Credentials file:
~/.config/charon/credentials, as[<backend id>]thenapi_key = "…".
AWS credentials (Bedrock without an API key, and EC2) come from AWS_ACCESS_KEY_ID and
AWS_SECRET_ACCESS_KEY; the Keychain (aws:<backend id> or aws); the credentials file’s
[<backend id>] or [aws] section; your ~/.aws profile (aws_profile or AWS_PROFILE); or
aws configure export-credentials, which covers SSO.
charon status and the app show where each key came from, never the key.