Configuration

The agentry CLI keeps its state in two small JSON files under ~/.agentry/. You rarely edit them by hand — agentry login, agentry init, agentry server use, and agentry profile use write them for you — but they're documented here for completeness.

Files

File	Written by	Holds
~/.agentry/agentry.json	login, init, server use, profile use	enrollment, device cert paths, current server + profile, API token
~/.agentry/state.json	sandbox use	the pinned sandbox id (so other commands can omit --sandbox)

Both are plain JSON, written 0600, in ~/.agentry/ (0700). Same path on macOS, Linux, and WSL2.

agentry.json

{
  "app_url": "https://app.agentry.run",
  "broker_url": "https://bridge.agentry.run",
  "device_id": "my-laptop",
  "cluster": "homelab",
  "profile": "dev",
  "device_cert_path": "/Users/you/.agentry/devices/my-laptop/cert.pem",
  "device_key_path": "/Users/you/.agentry/devices/my-laptop/key.pem",
  "ca_cert_path": "/Users/you/.agentry/devices/my-laptop/ca.pem",
  "api_token": "pat_…",
  "org": "Acme",
  "user_email": "you@example.com"
}

Field	Set by	Meaning
app_url	init	control plane this device enrolled against
broker_url	init	bridge dial target (returned by enrollment)
device_id	init	this machine's name
cluster	server use	the current server (sent as the X-Cluster header on tunnel calls). cluster is the on-disk/wire term; the CLI surface calls it the server.
profile	profile use	active env/binds profile within the server (empty = default)
device_cert_path / device_key_path / ca_cert_path	init	mTLS material for the bridge tunnel
api_token	login	personal access token for control-plane calls (server ls, sandbox ls, service catalog). Never sent over the bridge tunnel — that uses the device cert.
org / user_email	login	cached display strings

Treat the cert + token as secrets

The device cert/key and api_token authenticate every call as you on this machine. Lost or shared device → revoke it from the dashboard under Settings → Devices.

state.json

{
  "current_sandbox": "sbx_quill"
}

Kept separate from agentry.json so you can wipe the pinned sandbox without losing enrollment. The current sandbox flips many times a day; the current server changes rarely.

Environment overrides

The CLI honors three env vars — mostly for tests and scripts that want to keep state out of $HOME:

Env var	Overrides	Default
AGENTRY_CONFIG	full path to agentry.json	~/.agentry/agentry.json
AGENTRY_STATE	full path to state.json	~/.agentry/state.json
AGENTRY_APP_URL	default control-plane URL for init / login (same as --app-url)	https://app.agentry.run

# Run a second account out of a different directory:
AGENTRY_CONFIG=/tmp/acct2/agentry.json AGENTRY_STATE=/tmp/acct2/state.json \
  agentry login

There is no env var for the current server — set it with agentry server use <name> (or pin a single MCP session with agentry mcp --server <name>).

Reset

rm -rf ~/.agentry
agentry login
agentry init --app-url https://app.agentry.run --token <token>

Wipes local enrollment + certs. Doesn't touch anything server-side — your sandboxes and deployments keep running.

Next

• CLI reference — commands that read / write these files.
• Environment variables — the full env surface.