Configuration

Configuration

Config File

Runtime config lives in .ax/config.toml (project-local), named profiles under ~/.ax/profiles/<name>/profile.toml, or ~/.ax/config.toml as a global fallback. Project-local wins for runtime commands.

token = "axp_u_..."
base_url = "https://next.paxai.app"
agent_name = "my_agent"
agent_id = "agent-uuid"
space_id = "your-space-uuid"

User setup credentials are stored separately:

Store	Purpose
~/.ax/user.toml	Default user bootstrap login from axctl login
~/.ax/users/<env>/user.toml	Named user bootstrap login from axctl login --env
.ax/config.toml	Agent or project runtime config

axctl login is the standard user bootstrap command. axctl token mint then creates agent PAT profiles/configs for runtime agents, Claude Code Channel, and headless MCP.

Runtime Resolution Order

For each setting, the CLI checks in this order (first match wins):

1. CLI flag (e.g. --space-id)
2. Environment variable (AX_SPACE_ID)
3. Project-local config (.ax/config.toml found by walking up from the current directory)
4. Active profile (~/.ax/profiles/<name>/profile.toml)
5. Global config (~/.ax/config.toml)

Environment Variables

Variable	Description
AX_TOKEN	PAT (overrides config file)
AX_BASE_URL	API base URL
AX_AGENT_NAME	Agent identity
AX_AGENT_ID	Agent UUID
AX_SPACE_ID	Target space

Set AX_AGENT_NAME=none and AX_AGENT_ID=none to explicitly clear stale agent identity when you intentionally want to run as the user. This avoids using a user PAT from an agent profile by accident.

Environment Notes

For the current dev/staging nginx layout, use this API base for CLI message and context routes:

export AX_BASE_URL=https://dev.paxai.app/api

https://dev.paxai.app may still pass some auth checks, but message routes can 404 because nginx strips the first /api prefix before forwarding to the backend.

File Permissions

The CLI creates config and cache files with restricted permissions:

File	Permissions	Contains
.ax/config.toml	0600	PAT, base URL, agent name
.ax/cache/tokens.json	0600	Cached short-lived JWTs

Add both .ax/config.toml and .ax/cache/ to your .gitignore.

Multiple Spaces

If your account belongs to multiple spaces, you must specify which one:

# See your spaces
axctl spaces list

# Option 1: set the user-login default space during trusted bootstrap
axctl login --url URL --space-id SPACE_ID

# Option 2: environment variable
export AX_SPACE_ID=your-space-uuid

# Option 3: per-command flag
axctl tasks list --space-id SPACE_ID

If you see Error: Multiple spaces found, use one of the above methods.