Account setup

The CLI needs one credential: an Oxagen API key (ox_…) plus the org and workspace it acts in. The key identifies you, the person running the CLI, to the Oxagen API. The CLI makes no LLM calls of its own, so there is no model provider key to configure.

oxagen cost, oxagen logs, and oxagen telemetry work without a credential. Most platform commands need authentication. oxagen agent enroll uses your CLI login, or the one-time token from agent registration when you pass --token.

Install the Oxagen appCopy Anchor Link

To enroll a machine, install the app on it first. The app links the oxagen command onto your PATH on first launch. Installing the CLI covers the oxagen CLI on its own.

1. Create your Oxagen accountCopy Anchor Link

1. Go to app.oxagen.sh and click Create an account.
2. Enter your name, work email, and a password, or choose Continue with Google or Continue with GitHub. Oxagen emails you a verification link. Click it before you sign in.
3. On Name your organization, enter the organization's name, check its address and namespace, and click Continue. The namespace takes 2 to 6 characters and never changes, because every agent key starts with it.
4. On Connect a code host, connect GitHub or GitLab. Each workspace keeps its steering records in a steering repo there.
5. On Create the first workspace, name the workspace, click Create, then click Continue.

Two onboarding steps follow: Wrap an agent and Start a run. Once the first run reaches Oxagen, the app opens the workspace's Runs page at /{org}/{workspace}. Note your org slug and workspace slug. Workspace pages sit under /{org}/{workspace}/…, and the CLI needs both slugs.

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

2. Mint an Oxagen API keyCopy Anchor Link

The CLI authenticates to the platform with an API key (ox_…), not your password. The browser sign-in under Authenticate the CLI, below, makes a key for the CLI itself, so you need to make one here only for oxagen login --token, such as in CI or on a machine with no browser:

1. In the app, open Organization, then the API keys tab.
2. Click Create key and describe what will use the key. stella drafts the key's name, scope, role, and expiry, and you can change each one. For a key that acts in one workspace, set the scope to This workspace. Then click Create key. Ordinary keys have no arbitrary per-capability allowlist. See Authentication.
3. Copy the key now. It is shown only once.

A key acts in one workspace or across the organization. The CLI sends the key as a Bearer token.

3. Authenticate the CLICopy Anchor Link

Run oxagen login. The default flow opens a browser sign-in page:

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

After you sign in, the consent page asks which org and workspace the CLI acts in. Both pickers stay open even when you belong to only one. When you approve, the browser lands on app.oxagen.sh/cli/complete, and the token is already in your terminal. To preselect the org and workspace and skip the picker:

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

For CI and headless environments, pass the key directly. There is no browser and no interactive prompt:

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

To sign out, run oxagen logout. It revokes this machine's sign-in on the server, so the stored key stops working, then clears the stored login. If the server can't be reached, it still clears the login and warns that the key may still work. You can also revoke any of your command-line sign-ins in the app: open Account settings, choose Security, and find it under Command-line sign-ins. A token you passed with --token is an API key, not a sign-in, so oxagen logout leaves it working.

oxagen logout

Confirm the credentials work:

oxagen graph search -q "workspace context" --limit 1

Use environment variables insteadCopy Anchor Link

Every value also reads from the environment, which suits CI and provisioning scripts that must not run an interactive flow. Environment variables take precedence over the config file:

export OXAGEN_API_TOKEN="ox_…"
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. It defaults to https://api.oxagen.sh.

Where credentials liveCopy Anchor Link

The config file holds a secret. It lives under your home directory with your user permissions. Keep it off shared machines and out of version control.

Next stepCopy Anchor Link

You're authenticated. Go to the CLI quickstart to link a project and read your first run.