Reference

The config.json file.

pals init creates a config file at $XDG_CONFIG_HOME/progresspals/config.json with mode 0600 (owner read/write only). The other commands read and write this file as needed.

Location

The default config directory follows the XDG Base Directory spec:

Linux: $XDG_CONFIG_HOME/progresspals (typically ~/.config/progresspals)
macOS: ~/.config/progresspals

Override with --config-dir <path> on any command, or by running pals init --config-dir <path> explicitly.

Fields

versioninteger

Schema version of the config file. Bumped when fields are added or restructured so older CLIs can migrate forward cleanly.

identity_pathstring

Path to the libp2p identity.key file. The key itself is generated on the first server start (pals create / pals join / pals serve), not by pals init.

swarm_idstring

UUID of the swarm this config belongs to. Written by `pals swarm create` (operator side). One swarm per config directory.

swarm_secretstringsensitive

Per-swarm shared secret, base64-encoded (44 ASCII chars). Used to derive the AES-256-GCM activation encryption key via HKDF-SHA256. Generated client-side by `pals swarm create` and stored back here by `pals login` (joiner side).

invite_tokenstringsensitive

The invite token your peer redeemed. Used as a default when --invite-token is omitted on commands that need it.

peer_credentialstringsensitive

Per-peer credential returned by the backend after a successful pals login. Receipt of redemption.

supabase_access_tokenstringsensitive

Operator's Supabase Auth access token. Used as the Bearer credential on operator-side REST calls. Auto-refreshed via supabase_refresh_token on 401.

supabase_refresh_tokenstringsensitive

Operator's Supabase Auth refresh token. Used to mint a fresh access token when the current one expires.

supabase_user_idstring

UUID of the Supabase user that owns this config's swarm. Decoded from the access token's JWT 'sub' claim.

default_modelstring

HuggingFace model id used when pals create / pals join / pals serve are run without a positional MODEL argument.

default_peersstring[]

Bootstrap multiaddrs used when --peer is omitted on pals join / pals serve.

Shape

A populated config looks roughly like this. Values shown are placeholders.

{
  "version": 2,
  "identity_path": "/home/you/.config/progresspals/identity.key",
  "swarm_id": "<uuid>",
  "swarm_secret": "<base64-encoded, 44 chars>",
  "invite_token": "pp_inv_...",
  "peer_credential": "<opaque>",
  "supabase_access_token": "eyJ...",
  "supabase_refresh_token": "eyJ...",
  "supabase_user_id": "<uuid>",
  "default_model": "Qwen/Qwen3-8B",
  "default_peers": [
    "/ip4/HOST/tcp/PORT/p2p/PEER_ID"
  ]
}

Don’t check config.json into version control. It contains your swarm_secret and peer_credential. The CLI keeps it at mode 0600 so only your user can read it.

Env vars vs. config

Environment variables override config-file values. The general rule: the CLI checks an explicit flag first, then the env var, then the config field. This lets you keep secrets out of the file (set them as env vars instead) and override defaults per-invocation.

Next steps

Reference

Environment variables

How the CLI resolves env vars vs config values.

CLI

pals init

How config.json gets created in the first place.

Concepts

Security & trust

Why config.json is mode 0600.

Help

Troubleshooting

Config-related errors and fixes.