Skip to content

setup.md

Latest commit

 

History

History
110 lines (68 loc) · 3.02 KB

setup.md

File metadata and controls

110 lines (68 loc) · 3.02 KB

Setup and Authentication Guide

Why Claude Pro/Max is Required

Virtual agents run claude -p (headless mode) inside Apple Containers. This mode requires an OAuth token that is only available with an active Claude Pro or Claude Max subscription on claude.ai.

Without an active subscription, the CLI cannot authenticate the headless session and the agent will fail immediately with an authentication error.

How to Obtain Your Token

Step 1 — Active subscription

Make sure you have an active Pro or Max subscription on claude.ai. You can verify your plan under Settings → Subscription.

Step 2 — Login from Claude Code CLI

claude login

This command opens an OAuth flow in your default browser. Authorize access when prompted.

Step 3 — Verify the stored token

Once the OAuth flow is complete, the token is automatically stored in ~/.claude/. You can verify it exists:

ls ~/.claude/

You should see the credential files generated by the CLI.

Dual-Token Architecture

The system uses two distinct environment variables for the OAuth token, one on the host and one inside the container:

Context Variable Purpose
Host CLAUDE_CONTAINER_OAUTH_TOKEN Token stored as an environment variable in your shell
Container CLAUDE_CODE_OAUTH_TOKEN Token injected into the container, consumed by claude -p

How they connect

In the Makefile, the host variable is defined as:

HOST_TOKEN_VAR := CLAUDE_CONTAINER_OAUTH_TOKEN

And mapped to the container via the -e flag:

-e CLAUDE_CODE_OAUTH_TOKEN=$${$(HOST_TOKEN_VAR)}

This takes the value of CLAUDE_CONTAINER_OAUTH_TOKEN on the host and injects it as CLAUDE_CODE_OAUTH_TOKEN inside the container. The Claude CLI reads this variable automatically on startup.

Why two separate variables

  • Session isolation: The container session is independent from the host session. If an agent fails or its token expires, your local Claude Code session is not affected.
  • Credential collision prevention: Prevents the container from overwriting or interfering with the credential files in ~/.claude/ on the host.

Environment Setup

Add the following variables to your ~/.zshrc or ~/.bashrc:

# OAuth token for agent authentication in containers
export CLAUDE_CONTAINER_OAUTH_TOKEN=<your-oauth-token>

# Directory where agent worktrees will be stored
export AGENTS_HOME=~/agents

Apply the changes:

source ~/.zshrc   # or source ~/.bashrc

Verify the variables are set:

echo $CLAUDE_CONTAINER_OAUTH_TOKEN
echo $AGENTS_HOME

How to Obtain CLAUDE_CODE_OAUTH_TOKEN

Run the following command in your terminal:

claude setup-token

This generates the OAuth token and displays it in the output. Copy it and export it:

export CLAUDE_CONTAINER_OAUTH_TOKEN=<obtained-token>

To make it persistent, add the line above to your ~/.zshrc or ~/.bashrc.