Models and Agents

This is the page to read when you want to run a loop with a specific model - Claude, GPT, a local model, anything.

The short version: loopexec does not pick or call a model. It runs a bounded work loop around an agent command you supply, records which model that command used, and can isolate where the agent is allowed to reach. The model call lives entirely inside your --exec command.

The contract, stated plainly

--exec is where the model is chosen and invoked - loopexec runs that string verbatim. The --model-* flags do not select or constrain the model; they only record a pin into the receipt for replay and provenance, and nothing verifies the pin matches what your agent actually called. Plain loopexec run does not inject an API key; your agent reads its own key from the environment. Managed, per-run credentials are an isolate feature, not a run one.

Who owns what

Concern	Owner	How
Which model, which endpoint, which SDK	You / your agent	inside the --exec command
The API key, in a plain run	You / your agent	ambient env (e.g. ANTHROPIC_API_KEY, ~/.claude)
Recording which model ran	loopexec (run)	--model-* + sampling flags -> the receipt pin
Reaching + crediting the endpoint under isolation	loopexec (isolate) + operator infra	egress allowlist + per-run minted/revoked key
The container runtime, egress proxy, key API	Operator	--runtime / --egress-proxy / --mint-cmd + --revoke-cmd

loopexec orchestrates the loop; it is not the agent, the model, or a task runner.

1. Run a model in a loop

The simplest case: your agent command calls a model, and the loop runs it until the check passes. The API key is whatever your agent reads from the ambient environment - loopexec does not supply it here.

export ANTHROPIC_API_KEY=sk-...

loopexec run \
  --check "go test ./..." \
  --exec  "claude -p 'fix the failing test; edit files in place'" \
  --max-iterations 8

--exec is the only place the model is chosen. Swap it for whatever calls your model:

Claude Code : claude -p "<task>"
A custom agent : python agent.py --task "<task>"      # your script picks the model
A local model  : python agent.py --base-url http://localhost:1234/v1   # OpenAI-compatible

loopexec never parses or understands that command. It runs the work step, runs the --check oracle, and stops on a computed halt - regardless of which model you used.

2. Record which model ran (the receipt pin)

Add the --model-* and sampling flags so the receipt names the exact model. This is what makes loopexec replay and an audit trail meaningful. These flags only record - they do not change the call - so set them to match what --exec actually uses:

loopexec run \
  --check "go test ./..." \
  --exec  "claude -p 'fix the failing test'" \
  --model-provider anthropic \
  --model-id       claude-opus-4 \
  --model-version  2026-05 \
  --temperature 0 --seed 0 --max-tokens 4096

The pin lands in .loopexec/state.json and is signed by loopexec attest. Because nothing cross-checks the pin against the actual API call, treat it as a declaration you are responsible for keeping honest - if --exec calls a different model than --model-id says, the receipt is wrong and loopexec cannot catch it.

The loop.yml models.executor block is the declarative form of this pin. Today it feeds the receipt only; it does not select or switch the model.

3. Reach the endpoint under isolation (managed key)

Plain run trusts the ambient environment. For an unattended or untrusted loop, isolate runs the agent in an egress-constrained zone with a per-run minted, spend-capped key that is revoked when the run ends. The proxy, the mint/revoke hooks, and the runtime are operator-provided; loopexec only composes them (two-zone isolation).

loopexec isolate --execute --confirm \
  --exec  "claude -p 'fix the failing test'" \
  --check "go test ./..." \
  --runtime      docker \
  --egress-proxy http://egress-proxy:8080 \
  --egress-allow api.anthropic.com:443 \
  --key-env      ANTHROPIC_API_KEY \
  --mint-cmd     "my-mint-scoped-key --ttl 1h --cap-usd 5" \
  --revoke-cmd   "my-revoke-key"

What happens:

• The minted key is injected into the agent zone via a 0600 env-file as --key-env (default ANTHROPIC_API_KEY) - never on the argv, never in the receipt - and revoked after the run.
• --egress-allow (default api.anthropic.com:443) is recorded in the receipt and enforced by the operator’s allowlist proxy, so the agent can reach the model endpoint and nothing else.
• The exec zone that runs your check is separate and gets network: none.

To target a local model instead, point --egress-allow (and your agent’s base URL) at it - for example host.docker.internal:1234 for an OpenAI-compatible server - and drop --mint-cmd if the endpoint needs no key.

Run loopexec isolate without --execute to render the full launch plan (both zone commands, the egress allowlist, the credential lifecycle) without starting any containers.

If you are an agent reading this

Pick the model inside --exec (your own CLI or SDK call). Add --model-* to record it. Do not expect loopexec to choose, switch, or supply a key for the model in a plain run; reach for isolate when you need a managed, scoped credential. The honest Capabilities matrix is the source of truth for what is wired today.