Skip to content
Guides /Configuration

Guides

Page 2 of 6

Configuration

Where Charon keeps its files, every setting in charon.toml, and how it finds cloud keys.

3 sections · 2 min read

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:

TOML
[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:

  1. Environment variable: key_env if set, else BEDROCK_API_KEY or AWS_BEARER_TOKEN_BEDROCK (Bedrock), AZURE_OPENAI_API_KEY (Azure), CLOUDSDK_AUTH_ACCESS_TOKEN (Vertex AI), or OPENAI_API_KEY (api.openai.com only).
  2. macOS Keychain: key_ref = "keychain:<account>", service charon. The app and --key-from-keychain save keys here.
  3. Credentials file: ~/.config/charon/credentials, as [<backend id>] then api_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.

↑↓to move↵to open