Harnesses

A harness is a named (host CLI + model) combo you run like a native agent. agents harness fork claude or-claude --model anthropic/claude-haiku-4.5 creates one; agents run or-claude "..." runs it. Point any host at any provider without editing shell profiles.

Three primitives

Running a host CLI against a provider it does not natively ship uses three things. There is no standalone provider command — a provider is a value you pass to accounts add.

account — a durable, device-local credential (an API key, a setup token, or a bearer token), stored the same way as any agents secrets bundle with prompt policy never, so an agent launch never raises a Touch ID sheet.
provider — which upstream the credential talks to (openrouter, anthropic, openai, xai, deepinfra, and more) and which env vars it maps onto for each host.
harness — the named host-and-model combo. Fork a native host, pin a model, and attach an account. Omit the account to use the host's own native login.

How a provider maps onto a host

A provider injects one credential into the env vars each host CLI already reads. For openrouter:

host      auth env               base-url env
claude    ANTHROPIC_AUTH_TOKEN   ANTHROPIC_BASE_URL=https://openrouter.ai/api
codex     OPENAI_API_KEY         OPENAI_BASE_URL=https://openrouter.ai/api/v1
opencode  OPENROUTER_API_KEY     -

Fork a harness onto a provider account

Create the account once, then fork any number of harnesses onto it. The credential is read at launch and injected into the host's env — nothing is written to a shell profile.

agents accounts add openrouter --provider openrouter --auth api-key

agents harness fork claude or-claude --model anthropic/claude-haiku-4.5 --account openrouter
agents harness fork codex  or-codex  --model openai/gpt-4o-mini        --account openrouter

agents run or-claude "explain this stack trace"

One account backs many harnesses. agents accounts set-default claude openrouter makes it the default when --account is omitted; agents accounts list shows every account and native login.

Use a subscription, not an API key

Some hosts authenticate against a subscription over OAuth instead of a key. opencode signs in to a ChatGPT Pro/Plus subscription with a device-code flow — no API key, no account bundle. The token lives in the host's own auth store, so the harness carries no --account.

opencode auth login --provider openai --method "ChatGPT Pro/Plus (headless)"
#   Go to: https://auth.openai.com/codex/device
#   Enter code: XXXX-XXXXX   (authorize in a browser signed into the account)

agents harness fork opencode oc-sub --model openai/gpt-5.4-mini
agents run oc-sub "port this test to vitest"

This is a native-login harness: the credential is the host's OAuth token, distinct from a --provider account bundle. Both run the same way — agents run <name>.

Manage them

agents harness list                 # your custom harnesses
agents harness view or-claude       # host, model, provider, account
agents harness edit or-claude --model anthropic/claude-3-haiku
agents harness remove or-claude     # keeps the keychain token

Related: Secrets, Profiles, Run, Rotate accounts.