Account setup

The CLI uses two independent credentials. This page sets up both, in order:

1. A gateway key so the coding agent can call models. This is all you need to start coding.
2. An Oxagen account and platform token so the CLI can reach your knowledge graph, environments, and secrets.

1. Provide a gateway key (for the agent loop)

The agentic coding loop calls models through the Vercel AI Gateway using your own key — you bring your own key (BYOK). Get one from the Vercel dashboard under AI Gateway → API keys, then make it available to the CLI.

The CLI resolves the key in this order — the first one found wins:

1. AI_GATEWAY_API_KEY in your shell environment
2. env.AI_GATEWAY_API_KEY in ~/.oxagen/settings.json
3. gatewayKey in ~/.config/oxagen/config.json
4. The nearest .env.local walking up from your working directory

The quickest path — export it in your shell:

export AI_GATEWAY_API_KEY="vck_…"

To persist it across shells (recommended), write it into your user-scope settings. It is then projected into the environment on every run, and your shell still wins if you also export it:

oxagen settings set env.AI_GATEWAY_API_KEY "vck_…" --scope user

That is enough to start coding:

oxagen "summarize what this repository does"

Anthropic-only fallback: ANTHROPIC_API_KEY

No gateway key? If you only have an Anthropic API key, the CLI runs Claude models directly against the Anthropic API:

export ANTHROPIC_API_KEY="sk-ant-…"
oxagen "summarize what this repository does"

It resolves through the same chain (shell env → anthropicKey in ~/.config/oxagen/config.json → nearest .env.local) and is used only when no gateway key is found anywhere — AI_GATEWAY_API_KEY always wins when both are set.

Two limitations to know about: only anthropic/* models work (picking a model from another vendor fails with a clear error), and semantic code search runs without vector ranking (embeddings require the gateway).

2. Create your Oxagen account

You need an Oxagen account only for the platform commands (graph, env, secret). Creating one takes a minute:

1. Go to app.oxagen.sh and click Sign up.
2. Enter your name, email, and a password — or use Google / GitHub social sign-in. Email verification is not required in the current release; you are signed in immediately.
3. On the New organization screen, enter an organization name (a URL-safe slug is generated; you can edit it) and click Create organization. This also creates a default workspace, and you become the Owner of both.

You land at /{org}/{workspace}/ask. Note your org slug and workspace slug from the URL — the CLI needs them.

For a full tour of the app, see Getting started.

3. Mint a platform API key

The CLI authenticates to the platform with an API key (oxk_live_…), not your password:

1. In the app, go to Organization → Developer → Tokens.
2. Click Create API key, give it a name, and select the scopes it needs (at minimum, the capabilities you'll call — graph read, environments, secrets).
3. Copy the key now — it is shown only once.

API keys carry org and workspace scope and are passed as a Bearer token by the CLI.

4. Authenticate the CLI

Run oxagen login to authenticate. The default flow opens a browser-based OAuth page:

oxagen login            # opens a browser — follow the prompt, then pick your org and workspace

After logging in, an interactive picker lets you choose your org and workspace. To pre-select them and skip the picker:

oxagen login --org your-org-slug --workspace your-workspace-slug

For CI / headless environments, pass the token directly — no browser, no interactive prompts:

oxagen login --token oxk_live_… --org your-org-slug --workspace your-workspace-slug

To sign out and clear the stored session:

oxagen logout

Confirm the credentials work:

oxagen graph status

Advanced: raw config setters (scripting)

For provisioning scripts that need to write credentials without any interactive flow, the raw config setters are available. They write to ~/.config/oxagen/config.json but do not validate the token or call the platform:

oxagen config token oxk_live_…
oxagen config org   your-org-slug
oxagen config workspace your-workspace-slug

Using environment variables instead

Every value also reads from the environment, which is handy for CI. Environment variables take precedence over the config file:

export OXAGEN_API_TOKEN="oxk_live_…"
export OXAGEN_ORG_ID="your-org-slug"
export OXAGEN_WORKSPACE_ID="your-workspace-slug"

To target a self-hosted or staging API, set OXAGEN_API_URL (or oxagen config api-url …); it defaults to https://api.oxagen.sh.

Where credentials live

Both files contain secrets. They live under your home directory with your user permissions — keep them off shared machines and out of version control. Project-scope settings (.oxagen/settings.json) are safe to commit; local secrets belong in .oxagen/settings.local.json, which is gitignored.

Next step

You're authenticated. Head to the Quickstart for your first agentic coding session.