Tool Setup

The unbound setup command configures AI coding tools to route through Unbound. It handles authentication, environment variables, and tool-specific config files automatically. If you are not logged in and --api-key is not provided, the browser opens automatically to authenticate before setup begins. Under sudo there is no browser step — setup stops with —api-key is required to set up tools (or run unbound login first). Do one of those two things.

Interactive setup

Run with no arguments to select tools from an interactive menu:

unbound setup

Default bundle

Install Cursor, Claude Code (hooks), Codex (hooks), Copilot (hooks), and Augment (hooks) in one command:

unbound setup --all

Individual tools

Cursor

unbound setup cursor

Claude Code

Claude Code supports two modes:

unbound setup claude-code --gateway        # Unbound as the AI provider — no Anthropic subscription needed
unbound setup claude-code --subscription   # Hooks only — keep your existing Anthropic subscription

Run without a flag for interactive mode selection.

The bare unbound setup claude-code (no flag) and unbound setup codex (no flag) commands open an interactive prompt to pick a mode. In a non-interactive shell (CI, SSH with < /dev/null, MDM bootstrap) the prompt has no input source and the command exits immediately without writing any config. Always pass --gateway or --subscription explicitly in headless environments.

Gemini CLI

unbound setup gemini-cli

Codex

unbound setup codex --gateway              # Unbound as the AI provider — no OpenAI subscription needed
unbound setup codex --subscription         # Hooks only — keep your existing OpenAI subscription

GitHub Copilot

unbound setup copilot

Hooks-based — works with both the VS Code extension and the copilot CLI on your existing Copilot subscription.

Augment Code

unbound setup augment

Hooks-based — works with both the Augment VS Code extension and the Auggie CLI.

Pi (Beta)

unbound setup pi

Extension-based — installs into pi’s extensions folder. Pi is not part of unbound setup --all. unbound onboard sets it up when pi is already on the device; otherwise install it on its own. unbound setup --all --clear does remove it. See Pi.

Instruction-only tools

These tools require manual configuration. The CLI prints the values to enter in each tool’s settings. Roo Code and Kilo Code need only their API provider set to Unbound plus your API key. Cline needs its API provider set to OpenAI Compatible, the gateway host with /v1 appended as its base URL, and your API key. Custom Access needs that same base URL and your API key.

Tool	Command
Roo Code	`unbound setup roo-code`
Cline	`unbound setup cline`
Kilo Code	`unbound setup kilo-code`
Custom Access (direct API)	`unbound setup custom-access`

Combine authentication and setup in a single command with --api-key:

# Single tool:
unbound setup cursor --api-key <key>

# Multiple tools (use explicit mode names when combining):
unbound setup cursor claude-code-gateway --api-key <key>

# Login, then select interactively:
unbound setup --api-key <key>

When specifying multiple tools in one command, use the explicit form names:

Short form	Explicit form
`claude-code --gateway`	`claude-code-gateway`
`claude-code --subscription`	`claude-code-subscription`
`codex --gateway`	`codex-gateway`
`codex --subscription`	`codex-subscription`

Remove configuration

unbound setup cursor --clear
unbound setup claude-code --clear
unbound setup gemini-cli --clear
unbound setup codex --clear
unbound setup copilot --clear
unbound setup augment --clear
unbound setup pi --clear

Remove every tool’s configuration in one command:

unbound setup --all --clear

Uninstall everything

unbound nuke (alias unbound uninstall) removes Unbound entirely and returns the CLI to a fresh state. When it finishes, run unbound login (or unbound onboard) to set things up again. What it removes. Per-tool configuration and hook scripts; the export UNBOUND_*_API_KEY and export ANTHROPIC_BASE_URL lines Unbound added to your shell profiles (or the equivalent user environment variables on Windows); the scheduled discovery scan and the API key it runs with; and ~/.unbound/config.json. Run as root it also removes a binary install — /opt/unbound, its scanner job, its log-rotation entry, and /var/log/unbound.

Failure reporting

When a setup step fails, your organization’s admins see it — this device’s hostname, the step that failed and its exit code — so a broken enrollment does not vanish on the device. Nothing else is sent — no hardware identifiers — and the error you see on the device is unchanged. The scope follows your privileges — no flag to pick:

# Without root: clears your tools + credentials (MDM/system-level config is skipped)
unbound nuke

# With root: also clears MDM (system-level) config for all users on the device
sudo unbound nuke

Add --yes to skip the confirmation prompt.

Setup flags

Flag	Purpose
`--api-key`	Authenticate inline rather than via the browser flow
`--subscription`	Claude Code / Codex in hooks mode — keep your own subscription
`--gateway`	Claude Code / Codex with Unbound as the AI provider
`--all`	Install the default bundle (Cursor + Claude Code hooks + Codex hooks + Copilot hooks + Augment hooks). Cannot be combined with explicit tool names
`--clear`	Remove a tool’s configuration instead of installing it
`--backfill`	Seed historical Claude Code / Codex / Copilot sessions from local transcripts into Unbound analytics, so past activity shows up. Subscription/hooks mode only — not supported in gateway mode, and Cursor and Augment are unsupported

One-step onboarding

unbound onboard runs setup --all followed by device discovery in a single command. Useful for new user enrollment:

unbound onboard --api-key <USER_KEY>

Pi is the one tool onboarding adds only where it is already in use. From CLI 1.16.20, unbound onboard also sets up Pi when it detects pi on the device, and skips it otherwise. Detected means the pi command is installed, or pi has been signed in to or run (~/.pi/agent/auth.json, ~/.pi/agent/sessions). With sudo, pi is looked for across every user on the device. Every other tool in the bundle is set up whether or not it is installed.

MDM setup (admin, requires root)

Scope is automatic: run unbound setup / unbound onboard with sudo to configure every user on the device (MDM/org scope), or without sudo to set up just the current user:

# Install the org-wide bundle for all users (adds Gemini CLI to the user bundle):
sudo unbound setup --api-key KEY --all

# Specific tools:
sudo unbound setup --api-key KEY cursor codex-subscription
sudo unbound setup --api-key KEY claude-code-subscription codex-subscription gemini-cli

# Remove config:
sudo unbound setup --clear cursor

For device-wide onboarding in one step:

sudo unbound onboard --api-key <ADMIN_KEY>

See MDM Integrations for deployment guides.

Getting Started

CLI

Policies

Analytics

Integrations

MDM Integrations

Connections

Support & Troubleshooting

Interactive setup

Default bundle

Individual tools

Cursor

Claude Code

Gemini CLI

Codex

GitHub Copilot

Augment Code

Pi (Beta)

Instruction-only tools

Remove configuration

Uninstall everything

Failure reporting

Setup flags

One-step onboarding

MDM setup (admin, requires root)

​Interactive setup

​Default bundle

​Individual tools

​Cursor

​Claude Code

​Gemini CLI

​Codex

​GitHub Copilot

​Augment Code

​Pi (Beta)

​Instruction-only tools

​One-step login + setup

​Remove configuration

​Uninstall everything

​Failure reporting

​Setup flags

​One-step onboarding

​MDM setup (admin, requires root)

Interactive setup

Default bundle

Individual tools

Cursor

Claude Code

Gemini CLI

Codex

GitHub Copilot

Augment Code

Pi (Beta)

Instruction-only tools

One-step login + setup

Remove configuration

Uninstall everything

Failure reporting

Setup flags

One-step onboarding

MDM setup (admin, requires root)