Documentation

Coding agent quickstart (CLI & MCP)

Install the CLI, add action-time hooks where supported, expose advisory MCP tools, and optionally apply Managed Profiles launch policy.

Install

Install the CLI, then confirm the version. For the Trajectus pilot, require 0.2.11 or newer — stop and contact the operator if the build is older.

npm (Windows / macOS / Linux)

npm install -g @behalfid/cli

curl (macOS / Linux only)

curl -fsSL https://behalfid.com/install.sh | sh

Optional version pin for install.sh — assign the variable to the executing shell (sh), not to curl:

curl with pinned version (macOS / Linux only)

curl -fsSL https://behalfid.com/install.sh | BEHALF_VERSION=v0.2.11 sh

Homebrew is macOS only:

Homebrew (macOS only)

brew install BehalfID/tap/behalf

Verify the install (required):

terminal

behalf --version

Setup wizard

Run behalf init to walk through base URL, authentication, and API key configuration interactively.

terminal

behalf init

The wizard stores config at ~/.behalf/config.json and session at ~/.behalf/session.

Auth

terminal

behalf login         # log in with email and password
behalf whoami        # show current authenticated user
behalf logout        # clear the session

Agents

terminal

behalf agents list
behalf agents create --name "My Bot"
behalf agents create --name "Ollie" --type connected --provider ollie --save

Pass --save to write the new agent ID and API key directly to ~/.behalf/config.json. The API key is only returned once.

Permissions

Permission grants require human authentication. Run behalf login or pass--developer-token with a bhf_dev_... developer token. Agent API keys are for verification only and cannot create or revoke permissions.

terminal

behalf login
behalf permissions create agent_xxx \
  --action access_data \
  --resource gmail.com \
  --allowed "read labels,summarize messages" \
  --blocked "send email,delete messages" \
  --requires-approval

behalf permissions create agent_xxx \
  --action purchase \
  --resource amazon.com \
  --max-amount 50 \
  --template purchase

Verify an action

Use behalf verify to run a one-off action check. The command exits with code 0 on allow and 1 on deny — safe to use in scripts.

terminal

behalf verify agent_xxx --action browse_web --vendor web
behalf verify agent_xxx --action purchase --vendor amazon.com --amount 25

Pass --json to get machine-readable output. The exit code still reflects the allow/deny decision.

terminal

behalf --json verify agent_xxx --action purchase --vendor amazon.com --amount 100

denied response

{
  "requestId": "req_xxx",
  "allowed": false,
  "reason": "Amount exceeds maxAmount constraint.",
  "risk": "high"
}

Logs

terminal

behalf logs agent_xxx

Advisory MCP server

BehalfID ships a Model Context Protocol (MCP) server that makes real-time verify_action and get_permissions available to any AI tool that supports MCP. Run behalf mcp init once per project to wire it in.

The MCP server is advisory: it gives the model tools and instructions, but it does not intercept another tool's execution. For Claude Code shell/file enforcement, use and verify the separate PreToolUse hook installed by behalf claude.

terminal

behalf config set agent-id agent_xxx
behalf config set api-key bhf_sk_xxx
behalf mcp init

mcp init writes two files to the current directory:

.mcp.json — registers the behalfid MCP server (merged with any existing config)
.behalf/context.md — a markdown brief of the agent's active permissions

If a CLAUDE.md or AGENTS.md file is present, the CLI offers to append @.behalf/context.md so the AI tool loads the context automatically on startup.

.mcp.json

{
  "mcpServers": {
    "behalfid": {
      "type": "stdio",
      "command": "behalf",
      "args": ["mcp", "start"]
    }
  }
}

The MCP server exposes get_permissions for inspection and verify_action for explicit advisory checks. The context file instructs the AI to call verify_action before risky or permissioned actions, stop on denied decisions, fail closed if verification is unavailable, and pause when approval is required.

terminal

behalf mcp status           # show config and cached permissions for this directory
behalf mcp init --refresh   # force-refresh the permissions cache from the server
behalf mcp init --dry-run   # preview what would be written without writing
behalf doctor               # diagnose CLI and MCP setup

Launch AI tools with BehalfID setup

The behalf claude, behalf codex, and behalf run commands fetch the latest permissions, write .behalf/context.md and .mcp.json, install supported action-time hooks, and then launch the tool. The context and MCP server are advisory; the Claude PreToolUse hook is the action-time gate. The launcher prints the agent, base URL, context file, MCP config, and command it is about to run. It does not print API keys.

terminal

behalf claude              # install/verify the Claude PreToolUse hook, then launch
behalf codex               # configure supported Codex hook/MCP setup, then launch
behalf run cursor          # configure supported Cursor hook/MCP setup, then launch
behalf claude --resume     # pass extra flags straight through to the tool

For a runnable local walkthrough with allowed, denied, and approval-required examples, see docs/MCP_DEMO.md.

Managed Profiles

Control what coding agents can do before they touch protected repos.

Managed Profiles let teams put coding-agent CLIs behind a workspace policy checkpoint, install local shims, resolve policy before the real tool starts, and record safe activity for review.

Enforce managed or required mode for protected repos
Simulate policy before launching a tool
Approve required-mode pause requests
Review activity without exposing raw paths or git remotes

First-run quickstart

terminal

npm install -g @behalfid/cli
behalf login
behalf profile install
behalf profile status --tool claude
behalf profile simulate --tool claude
claude

Ensure ~/.behalf/bin is early in PATH. Enable Managed Profiles policy in the dashboard before expecting enforcement.

Dashboard setup

The Managed profiles onboarding card walks through the same install → status → simulate → launch flow. After your first shim launch, enroll protected repos from Managed Profile Activity using repo hashes — not raw git remotes or local paths.

Policy simulation

terminal

behalf profile simulate --tool claude
behalf profile simulate --tool codex --repo 0123456789abcdef --branch main

Dry-runs policy resolution without launching a tool. The dashboard simulator uses the same API.

Protected repos and required mode

Enroll repos by policy repo hash (for example 0123456789abcdef). Set mode to managed or required. When BehalfID successfully returns a required policy, the managed launch path enforces required-mode prerequisites (agent credentials and a valid profile or session) before starting the tool.

Managed Profiles govern the BehalfID-managed launch path (shim → session-policy → real binary). Directly invoking the underlying binary, changing PATH precedence, deleting the shim, or otherwise intentionally bypassing the local integration is not prevented by the current implementation. Server-side policy evaluations, approval decisions, and authorization results remain authoritative when requests reach BehalfID. Local shim enforcement is best-effort and is not a tamper-resistant endpoint security control.

Required-mode pause approval

terminal

behalf pause --duration 30m --reason "incident response" --tool claude
behalf pause status apr_example

When pause approval is required, the CLI prints an approval id and dashboard link. Approvers review at Approvals or Needs attention.

Privacy

Activity and approvals show repo hashes, tool, branch, and device id — not raw git remotes, local source paths, home directories, or secrets. See Demo script for a 2–3 minute recording walkthrough and launch checklist.

Full CLI reference: packages/cli/README.md.

Troubleshooting first-run failures

Run behalf profile doctor first. Each warning or error includes a fix: line. Common issues:

~/.behalf/bin not first in PATH — Managed tools resolve the real binary instead of the shim. Add export PATH="$HOME/.behalf/bin:$PATH" to your shell config, restart the terminal, and confirm with behalf profile status (PATH ordering: ok).
Real claude/codex/cursor binary not found — Install the tool first. behalf profile install skips tools whose binaries are missing. Doctor shows which real binary could not be resolved.
Unauthenticated CLI — Run behalf login. Status and simulate need a session; when the server returns required, launches refuse to start without agent credentials.
Server unavailable — Behavior depends on the local policy cache. A fresh cached required policy causes the managed launch path to fail closed so a previously required context is not silently downgraded. If no usable cached required policy exists (missing or expired cache), the CLI may fall back to unmanaged operation so a BehalfID outage does not indefinitely block developer work. Check base URL with behalf config get base-url and network access to the API.
Required mode prerequisites — When mode is required and the server response is available, missing agent credentials or an incomplete profile/session cause the shim to refuse launch. That is separate from the outage fallback above: server-down with no usable required cache may continue unmanaged; server-down with a fresh cached required policy fails closed.
Protected repo hash not appearing — Run from inside a git repo. Status shows policy repo hash; if (none), confirm git remote or local root detection. Enroll only after a shim launch records activity.
Activity not appearing after launch — Confirm PATH order (shim, not real binary), authentication, and that Managed Profiles policy is enabled in the dashboard. Wait a few seconds and refresh Activity.

For a printable pass/fail checklist, see the fresh-workspace smoke test. Deeper verify/auth/webhook diagnosis: Troubleshooting.

Deploy approval workflow

The most common first use case: an AI coding agent (Claude Code, Codex, Cursor) that can deploy to staging autonomously but must pause for human approval before touching production.

1. Set up permissions

Create two permissions for your coding agent — one that allows staging deploys without approval, and one that requires approval for production.

terminal

# Allow staging deploys — no approval required
behalf permissions create agent_xxx \
  --action deploy \
  --resource vercel.com \
  --allowed "deploy to staging, create preview deployment" \
  --blocked "deploy to production, promote to production"

# Production deploy requires human approval
behalf permissions create agent_xxx \
  --action deploy_production \
  --resource vercel.com \
  --allowed "promote staging to production" \
  --requires-approval

2. Launch your AI tool with BehalfID setup

terminal

behalf config set agent-id agent_xxx
behalf config set api-key bhf_sk_xxx
behalf mcp init
behalf claude       # or: behalf codex

3. The approval flow in practice

In this advisory MCP example, when the agent attempts a production deploy, it calls verify_action(action: "deploy_production", vendor: "vercel.com"). BehalfID returns "allowed": false, "reason": "Permission requires approval before execution.". The agent pauses and reports the requestId. You approve in the dashboard or via webhook, then the agent retries — now allowed. This model-mediated flow is not the Claude Code action-time hook and should not be used as proof of shell non-execution.

what the agent sees

verify_action("deploy_production", "vercel.com")

{
  "requestId": "req_Abc123xyz",
  "allowed": false,
  "reason": "Permission requires approval before execution.",
  "risk": "medium"
}

→ Agent pauses: "Deployment to production requires approval (req_Abc123xyz)."
→ Webhook fires to your configured endpoint (Slack, PagerDuty, etc.)
→ You approve in the BehalfID dashboard
→ Agent calls verify_action again → allowed → deploy runs

4. Audit the decisions

Every verify call — allowed, denied, and approval-required — is logged with a stable requestId. Filter by decision type in the Logs view or export as CSV for post-mortems.

terminal

behalf logs agent_xxx          # tail recent verification decisions

Config

terminal

behalf config set api-key bhf_sk_xxx
behalf config set agent-id agent_xxx
behalf config set base-url https://behalfid.com
behalf config get api-key
behalf config list

Global --json flag

Add --json before any subcommand to get machine-readable output. Errors are also emitted as JSON. Works with every command.

terminal

behalf --json agents list
behalf --json verify agent_xxx --action purchase -v amazon.com