Connect your agent

Ironhide is a referee for your real agent. You run the agent you are about to ship — in your own pipeline, on your own infrastructure — and Ironhide drives it through adversarial episodes and returns a result on what it actually did. There is nothing for you to expose: Ironhide never calls out to your agent. You authenticate with an API key and your results flow inbound.

That shapes the whole connection story. There is exactly one connection mode: ci. You register an agent, get a wk_live_ key, and from then on every episode you drive and every CI run authenticates with that key.

Log in first#

An account owns all of your agents; billing, the plan, and the shared free-run pool live on the account. Log in (or sign up) before you connect:

$ ironhide login --email you@acme.dev

A new email creates an account and mints an owner key (shown once — save it). An existing email logs in with --owner-key. The CLI stores credentials in ~/.ironhide/config.json (chmod 600); Ironhide keeps only a hash.

Register a CI agent#

ironhide connect registers a ci agent under your account, mints the wk_live_ token, and prints it exactly once:

$ ironhide connect --name "AcmeAgent" --email sec@acme.dev

ok - registered  agt_9f2c11  (data owned)
  IRONHIDE_API_KEY:  wk_live_4c8d0e...
  shown once - saved to ~/.ironhide/config.json (chmod 600). Ironhide stores only a hash.

  The environments your agent is tested against are added to Ironhide's shared
  attack library to make future tests harder. Your agent's own prompts and code
  are not resold.

next - gate it in your pipeline:
  * add the token to your CI secrets as IRONHIDE_API_KEY
  * add the GitHub Action ironhide-ai/ironhide-scan@v2.5.0 (or run ironhide test in your pipeline)
  * every run returns a verdict on the ironhide/referee check

Hit your plan's agent limit? An interrupted connect can register an agent without saving its key. Run ironhide agents to see it, then ironhide agents rotate-key <agent_id> for a fresh key, or ironhide agents delete <agent_id> to free the slot (the console's Agents screen has a Delete button too).

The same registration is one API call, owner-authenticated. mode must be "ci" — the server 422s any other value:

$ curl -s https://app.ironhideai.com/agents \
    -H "Authorization: Bearer $IRONHIDE_OWNER_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "AcmeAgent",
      "mode": "ci",
      "contact_email": "sec@acme.dev"
    }'

{
  "agent_id": "agt_9f2c11",
  "api_key": "wk_live_4c8d…",
  "data_rights": "owned",
  "status": "unverified",
  "contract_version": "v2",
  "plan_id": "developer",
  "subscription_status": "trialing",
  "free_run_limit": 100
}

New registrations are on Agent Contract v2, the default and only customer contract — see the agent contract.

Every run is stamped owned — there is no data-rights choice to make and no data_reuse_opt_in field to send. What Ironhide keeps and reuses is the scrubbed environment your agent ran against, not your trajectory. See data rights.

Verify the connection#

Every agent starts unverified and cannot drive real episodes until it has been verified. Because your agent runs in your own pipeline there is nothing to probe: verification confirms your credential resolves to this agent and stamps it verified. Run it as often as you like — no trajectory is recorded:

$ ironhide verify

See verify the connection for what the probe checks and how to read the result.

Drive an episode#

With the agent verified, drive a single episode locally. ironhide episode list shows the episodes you can drive, each under a stable per-account alias (ep_...). You point the CLI at one alias and at a small adapter — a callable that wires your real agent into the episode:

$ ironhide episode list
$ ironhide episode run --episode-id ep_5b1c0f4a9d22 \
    --adapter my_pkg.agent:run

The CLI pulls the episode manifest, lets your adapter drive it, submits the resulting trajectory, and renders the verdict — pass, fail, warn, or inconclusive — with its reason and any applicable severity. Most episode results are held-out, so evidence is empty and protected measurements can be null. Featured results can include available detail. An agent that speaks MCP can be driven without an adapter at all; see Connect any MCP agent. See running an evaluation for the full episode flow, the adapter contract, and how the result reads.

Gate it in CI#

Once you can drive episodes, wire the referee into your pipeline so every change is checked before it ships:

• GitHub Action — ironhide-ai/ironhide-scan@v2.5.0, pinned with the release's CLI digest (cli_sha256) and a driver (adapter or agent_factory), posting the result on the ironhide/referee check.
• GitLab CI — the job ironhide link adds runs on merge requests and on pushes to the default branch, and caches the baseline between pipelines.

Both are thin wrappers around ironhide test, which gates the runs captured for your agent (and, given --adapter, drives the whole suite first). Store your wk_live_ key as the IRONHIDE_API_KEY secret; never commit it.

Next steps#

• Verify the connection: the connection test and its error codes.
• Agent contract: contract v2, the wire every connected agent speaks.
• Running an evaluation: drive episodes locally and gate in CI.
• Episode library: what the referee runs your agent through.