Using One Connect

Agents and subscriptions

Every agent runs through its vendor's official tool, signed in with your own account. Here is how to set each one up, how billing is guarded, and every option an agent has.

Supported agents#

One Connect never extracts or stores vendor sign-in credentials, and it ships no vendor binaries. It only asks each official tool whether it is signed in.

Personal use or API keys only#

Settings → Project and policies → Accounts & vendor terms sets policies.accounts.mode:

policies:
  accounts:
    mode: personal             # or api-keys-only
    terms_max_age_days: 90     # re-confirm own-account use this often
    api_key_rotation_days: 90  # reminder to rotate stored keys (never blocks)

Set up an agent#

Open Settings → Agents and sign-in. For each vendor:

1. Install the harness from the vendor. The page lists each vendor's official install commands. In the Mac app, Prepare in terminal puts the command in your project terminal; nothing runs until you press Return.
2. Sign in with the vendor's own command, or choose Use an API key instead.
3. Check the plan. The agent's billing should read included plan.
4. Turn paid overage off in the vendor account. One Connect stops a run when a vendor reports overage in use, but it cannot see every account setting.
5. Confirm own-account use (below), then record your payment confirmation when the official CLI cannot expose overage settings itself.

Create an agent opens the agent builder, where you choose the harness and model source, name and role, model rule, instructions and skills. Saved agents can stay disabled as drafts: a disabled agent is never probed or dispatched.

Own-account confirmation#

Before a subscription agent's first dispatch you confirm, once per vendor login, that:

• the login is your own, and you signed in through the vendor's own flow;
• only you use it through One Connect, and any paired phone is your own device;
• you run the vendor's CLI unmodified, and nobody copies its login tokens;
• you read the linked vendor terms, and your use fits them.

The confirmation is an audited event and survives restarts. It stops counting when it is older than terms_max_age_days (a reminder appears 14 days before), when the vendor terms revision One Connect links to changes, when a different account signs in to that CLI (for CLIs that report the account: Claude Code and Cursor), when you withdraw it, or when the workspace switches to api-keys-only.

One Connect stores only an opaque fingerprint of the signed-in account and a masked label such as al…@example.com. It never reads the CLI's credential files or tokens. Confirmations can only be recorded at the Mac, never from a paired phone.

Payment confirmation#

Where the official CLI cannot report overage, purchased credits or auto-recharge, dispatch stays blocked until you check the signed-in account and confirm those are off. This is your attestation; the vendor setting keeps showing unknown. It applies only to that agent, its current runtime and login observations and this daemon session, for at most 12 hours. A fresh probe, a changed runtime, login or configuration, a restart or expiry asks for it again.

Background checks#

• Every 15 minutes, a watch asks each idle subscription CLI whether it is still signed in, and re-checks the agent when the login or the account changed. An expired login raises an alert and blocks dispatch.
• On macOS, each probe checks the binary's code signature: Anthropic PBC for Claude Code, OpenAI for Codex. A broken signature, or one from another developer, blocks dispatch. An unsigned launcher such as an npm shim only warns. Cursor ships its CLI unsigned, so it is not checked.
• Stored API keys older than api_key_rotation_days raise a rotation reminder.

Claude Code#

• Install: curl -fsSL https://claude.ai/install.sh | bash, or brew install --cask claude-code, or npm install -g @anthropic-ai/claude-code.
• Sign in: claude auth login, then check with claude auth status. "authMethod": "claude.ai" means your subscription.
• Usage: during runs Claude Code reports its 5-hour and 7-day windows and the overage status. One Connect shows these as usage meters and stops the run if overage is in use without a metered opt-in.
• Overage: claude.ai → Settings → Usage → Extra usage. Keep it off.
• ANTHROPIC_API_KEY and the Bedrock and Vertex variables are stripped from agent runs.
• Messages you send during a run reach Claude live. Tool permission requests come to One Connect through --permission-prompt-tool.
• API-key route: model source Anthropic API key, with the key stored in the Keychain.

Codex#

• Install: curl -fsSL https://chatgpt.com/codex/install.sh | sh, or brew install --cask codex, or npm install -g @openai/codex. The ChatGPT desktop app may bundle a newer codex; onboarding shows every copy and you can pin one with binary:.
• Sign in: codex login → Sign in with ChatGPT, then check with codex login status.
• Models: read from codex debug models, the CLI's own catalog.
• Usage: 5-hour and weekly windows, read from the session files of runs One Connect started. Other sessions are never read.
• Overage: if you bought Codex credits, make sure auto-recharge is off.
• Codex runs with --ignore-user-config and the workspace-write sandbox. Its current adapter records complete messages rather than token-by-token streaming; messages you send during a run are queued for the next turn.
• API-key route: model source OpenAI API key, billed separately from ChatGPT.

Cursor#

• Install: curl https://cursor.com/install -fsS | bash. It installs to ~/.local/bin; add that to your PATH if needed.
• Sign in: cursor-agent login, then check with cursor-agent status. The plan tier comes from cursor-agent about.
• Overage: on-demand (usage-based) pricing is an account setting the CLI cannot report, so it shows as unknown. Turn it off in the Cursor dashboard. CURSOR_API_KEY from your shell is stripped from subscription runs.
• API-key route: model source Cursor API key (provider: cursor-api, metered_opt_in: true). Only that agent's runs and probes receive the key, as CURSOR_API_KEY.

Google AI Pro: Antigravity and the Gemini app#

These are desktop and chat apps, so they use adapter: relay. One Connect gives you a self-contained prompt; you paste it into the app, then paste the reply, with its handoff block, back into the agent console. Relay agents cannot work entirely inside the dashboard, and the Designer never uses them. Gemini CLI can also be configured as a generic-cli agent.

Any other CLI#

A generic-cli agent runs any command-line agent with its own login. Give it a command and an args template; the placeholders {prompt}, {model}, {cwd} and {effort} are filled in at launch, and a --flag {model} pair is dropped when its value is unset. When no argument contains {prompt}, the prompt is written to standard input instead (stdin: prompt, the default); stdin: none sends nothing.

agents:
  - id: gemini-cli
    name: Gemini CLI
    role: researcher
    adapter: generic-cli
    command: gemini
    args: ["-p", "{prompt}"]

API keys, local models and OpenCode#

Subscription agents use their vendor CLI and your login. For API keys and local models, install the official OpenCode release yourself and create an agent with a model source; OpenCode is selected for you.

• Install: npm install -g opencode-ai@1.18.35. One Connect accepts exactly OpenCode 1.18.35 and refuses other releases, development builds and unknown versions. An executable rg (ripgrep) must be on your PATH, because OpenCode would otherwise download one.
• Model sources: Anthropic, OpenAI or OpenRouter API keys; Ollama on this Mac; Ollama cloud through a signed-in local Ollama (ollama signin, ollama pull <model>:cloud) or an Ollama API key. LM Studio is blocked until its tool-calling contract is verified.
• Isolation: each run starts an authenticated OpenCode server on 127.0.0.1 in the agent's worktree, with its own config, home and cache. It receives only the selected provider key, works offline for packages, and never downloads plugins or models.
• Keys are stored under API keys in the macOS Keychain, never in settings, prompts, skills or tracker comments.
• Only installed, verified tool-capable Ollama models are selectable, and the bridge re-checks the model, route and authentication before each prompt.

See the repository's harness notes for protocol details.

Billing guard#

Opting into metered billing#

Not recommended, and only ever per agent. API-key providers require it:

agents:
  - id: api-claude
    name: Claude (API)
    role: engineer
    adapter: opencode-server
    provider: anthropic-api
    metered_opt_in: true
    budget_usd_per_day: 10
    pricing: { input_per_mtok: 3, output_per_mtok: 15 }

The UI then shows a red METERED banner everywhere the agent appears, and pre-flight warns on every dispatch. In the app, Review cost approval in the agent builder binds the exact configuration, model, prices, enabled state and daily stop threshold, asks for a second confirmation and expires after fifteen minutes.

Choosing models#

• model: newest picks the newest eligible model, optionally within model_family (for example opus or claude-opus). Anything else is a literal model id.
• allowed_models limits an agent; policies.allowed_models and policies.denied_models apply to every agent.
• Quality floors map issue categories to a minimum model class, for example schema_security: "opus-class high". Categories come from issue labels through project.categories.
• effort sets reasoning effort where the tool supports it: low, medium, high, xhigh or max.
• If a vendor serves a different model than the one requested, One Connect raises an alert.

Agent options#

The full schema, including model sources and endpoints, is in the configuration reference.