Test locally

A Local Run loads the checked definition and executes its real step bodies on your machine. Every ctx.sapiom.* call is resolved by the local stub client, so the run needs no Sapiom account, makes no Sapiom capability request, and creates no Sapiom capability spend.

Your code is still real

Local Run is not a sandbox. Direct fetch, filesystem access, environment reads, child processes, and third-party SDK calls in your own code still happen and can incur their own effects or charges. check can also run top-level effects when it imports the definition.

Run the happy path

Agent Studio

Bind the intended project, then choose Local Run in the action bar. This is a direct product action: it does not prompt Claude or use Claude credits.

The button currently sends {} as the entry input. Give every required entry field a schema default when you want the button to run unchanged. For custom input, use the authoring MCP route.

Claude Code with MCP

Ask Claude to call sapiom_dev_agents_run_local:

{
  "dir": "/absolute/path/to/hello-agent",
  "input": { "name": "Ada" }
}

The Hello Agent result includes a run-specific execution ID. The stable fields are:

{
  "outcome": "completed",
  "output": { "greeting": "Hello, Ada!" },
  "steps": [
    {
      "step": "greet",
      "input": { "name": "Ada" },
      "status": "succeeded",
      "output": { "greeting": "Hello, Ada!" }
    }
  ],
  "unusedStubs": [],
  "stubWarnings": []
}

An empty input produces { "greeting": "Hello, world!" }, proving the entry schema default was applied before the step ran.

Use built-in defaults first

You can start with the scaffolded file:

{
  "version": 1,
  "steps": {}
}

Calls without a project override use typed defaults from @sapiom/tools. This is enough to trace control flow, but the returned data is test data—not provider evidence.

Steer a capability branch

Stub overrides are scoped by the step that makes the call, then by the exact capability path:

{
  "version": 1,
  "steps": {
    "kickoff": {
      "models.coding.launch": {
        "status": "failed",
        "result": { "success": false },
        "error": {
          "stage": "run",
          "message": "compile failed"
        }
      }
    }
  }
}

Save that object in .sapiom-dev/stubs.json, or pass the same object as the stubs argument to sapiom_dev_agents_run_local.

Explicit stubs replace the file

The tool uses an explicit stubs object instead of .sapiom-dev/stubs.json; it does not merge the two. If neither is supplied, only built-in defaults apply.

Each configured response is returned verbatim. An array is the response itself for a list-returning method such as repositories.list; it is not a sequence of responses. Namespace calls use their namespace path (repositories.list, models.coding.launch). Methods on an attached handle use the singular handle path (repository.pushFromSandbox, sandbox.exec).

Read the result as evidence

1. Check the terminal outcome

   completed reached terminate(...); failed reached fail(...), exhausted a step attempt, or encountered an error. Read output or error rather than treating process exit alone as the assertion.

2. Inspect every step attempt

   steps is execution order, including retries. Each record carries the parsed input that author code received, status, output or error, logs, and captured Sapiom calls when present.

3. Require clean stub diagnostics

   unusedStubs identifies supplied keys that no call matched in a step that actually ran. stubWarnings identifies a key that matched but returned an implausible shape. A completed run with either list non-empty is not a clean test.

A stub under an unvisited branch is not reported unused, because that step never ran. Test each meaningful branch deliberately.

Pause and retry behavior

• A dispatched capability such as models.coding.launch records its stub result and automatically resumes the declared resume step with that value.
• A manual pauseUntilSignal({ ... }) also auto-resumes locally, but with {}. The local runner has no manual-signal payload override; make optional input safe for the happy path and test payload-dependent approval/rejection through the cloud signal path.
• Local and cloud execution default to three attempts per step. Raising maxAttemptsPerStep in a local call does not raise the cloud ceiling.
• Local Run stops after 1,000 graph advances as a final guard against a non-terminating graph.

What a passing Local Run does not prove

It does not prove provider availability, live credentials, real capability response shapes beyond the stub validators, cloud build success, or production runtime environment. Continue to deploy and production-run testing only after the local outcome and both stub-diagnostic lists are clean.

Build Fix types, manifests, or graph validation before rerunning locally.

Deploy Turn the checked working tree into an immutable ready cloud build.