Quickstart: Claude in Workcell

August 5, 2026 ยท View on GitHub

This guide assumes a supported Apple Silicon macOS host. GitHub-hosted CI and tagged-release install verification currently cover macos-26 and macos-15; the strongest local boundary claim still depends on local Colima validation.

Prerequisites

  • Workcell installed with ./scripts/install.sh
  • a repo you want to mount as the workspace
  • a reviewed Claude auth export, a reviewed Claude API key file, or a fail-closed macOS resolver scaffold config (manual support tier today)

1. Create or update the injection policy

Launch-ready paths today:

Reviewed exported Claude auth file:

workcell auth set \
  --agent claude \
  --credential claude_auth \
  --source /Users/example/.config/workcell/claude-auth.json

Reviewed API key helper path:

workcell auth init
workcell auth set \
  --agent claude \
  --credential claude_api_key \
  --source /Users/example/.config/workcell/claude-api-key.txt

Optional fail-closed macOS resolver scaffold:

workcell auth set \
  --agent claude \
  --credential claude_auth \
  --resolver claude-macos-keychain \
  --ack-host-resolver

The resolver records the intended host auth source. Workcell stops preparation and launch because no supported export path exists. Use this scaffold only to record policy intent. Check its state with workcell auth status --agent claude.

2. Optional explicit prepare

If you configured a launch-ready Claude auth input such as claude_auth or claude_api_key, a normal strict launch prepares the reviewed runtime image automatically when needed:

workcell --agent claude --workspace /path/to/repo

Use --prepare-only when you want to prewarm without launching:

workcell --prepare-only --agent claude --workspace /path/to/repo

3. Check the derived state

workcell --agent claude --doctor --workspace /path/to/repo
workcell --agent claude --inspect --workspace /path/to/repo
workcell auth status --agent claude
workcell --agent claude --auth-status --workspace /path/to/repo

workcell auth status reports the host policy view. --auth-status reports the staged launch view after selector evaluation and resolver preprocessing.

If you configured only claude_auth via the fail-closed macOS resolver scaffold, expect credential_resolution_states=claude_auth:configured-only and provider_auth_mode=none until a supported export path exists. The bootstrap summary will also report provider_bootstrap_path=host-export-scaffold and provider_bootstrap_support=manual.

4. Launch Claude

workcell --agent claude --workspace /path/to/repo

Prompt-mode autonomy:

workcell --agent claude --agent-autonomy prompt --workspace /path/to/repo

Managed development lane:

workcell --agent claude --mode development --workspace /path/to/repo -- bash -lc 'rg TODO'

5. Optional reviewed MCP state

If you want Claude to use a reviewed MCP registry instead of the empty safe baseline:

workcell auth set \
  --agent claude \
  --credential claude_mcp \
  --source /Users/example/.config/workcell/claude-mcp.json

6. Publish the result on the host

./scripts/pre-merge.sh --profile pr-parity
./scripts/repo-publish-pr.sh --workspace /path/to/repo --branch feature/my-change \
  --title-file /tmp/pr-title.txt --body-file /tmp/pr-body.md \
  --commit-message-file /tmp/commit-message.txt

Further reading