Run a governed coding task

Hand a coding agent one committed slice of your repository and get back a patch whose signed record the recipient checks before it touches their checkout.

The session imports the selected commit into a private workspace. A process worker calls separately authorized model and repository tools, and the result command exports the patch with its original signed receipts. Your checkout keeps its dirty and untracked files, and applying the patch stays a separate decision.

1. Build the worker and execution images

The operator supplies a runtime profile for three installed Docker images: the coding worker, the repository command environment, and the snapshot helper. The worker receives neither provider credentials nor Docker access; the trusted model gateway and repository service hold those on the operator side.

docker build -f operator/worker.Dockerfile -t chio-coding-worker .
docker build -f operator/execution.Dockerfile -t chio-coding-python .
uv run chio-mini-swe runtime-profile \
  --worker-image chio-coding-worker \
  --execution-image chio-coding-python \
  --helper-image python:3.11-slim --out runtime.json

You should see runtime.json with the immutable ID of each installed image. The Dockerfiles install the coding entry point and the Python, Bash, Git, and timeout tools the task uses. The profile command inspects images already installed; it pulls nothing and leaves running sessions as they are. Repository commands run without network access, so the command image carries every project dependency; this sample uses only Python's standard library.

2. Commit the sample and its bug

The sample has one bug: add subtracts its arguments. The task asks the agent to fix it and keep the tests, which makes the patch easy to review before you assign a larger repository. The project README lists the application files and the recovery tests.

def add(a, b):
    return a - b

import unittest
from calculator import add


class Addition(unittest.TestCase):
    def test_positive(self):
        self.assertEqual(add(2, 3), 5)

    def test_negative(self):
        self.assertEqual(add(-2, -3), -5)


if __name__ == "__main__":
    unittest.main()

uv sync
git -C sample init
git -C sample add package
git -C sample commit -m "Add calculator exercise"

You should see one commit in sample/ holding the package/ subtree. Git records it under your configured author identity; only committed content becomes session input.

3. Bind the task to the commit and its scope

session.json selects the sample repository, its committed package/ subtree, the runtime profile, and the agent's limits. Initialization resolves HEAD to an exact commit, and issue.md carries the task text.

{
  "schema": "chio.mini-swe.session-config.v3",
  "chio": "chio",
  "repository": "sample",
  "revision": "HEAD",
  "source_paths": [
    "package"
  ],
  "provider_config": "provider.json",
  "runtime_profile": "runtime.json",
  "command_timeout_seconds": 90,
  "agent": {
    "system_template": "Repair the repository using bash commands. Validate the change. Submit by running a command whose output starts with COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT, followed by your summary.",
    "instance_template": "{{task}} Work in these repository paths: {{source_paths}}",
    "step_limit": 8,
    "cost_limit": 1,
    "wall_time_limit_seconds": 600
  },
  "max_attempts": 2,
  "timeout_seconds": 300,
  "max_calls": 32,
  "capability_ttl_seconds": 3600
}

The calculator's add function subtracts instead of adding. Fix the function in
package/calculator.py. Preserve the tests and run them to verify positive and
negative inputs. Do not modify files outside package/.

uv run chio-mini-swe session init --config session.json \
  --task-file issue.md --state .session

Each entry in source_paths is a literal repository-relative path from the selected commit, never a glob. The scope is bound into the repository configuration, the tool manifest, and every completed command receipt; a file created or published outside it stops the workspace without promoting that revision. The v1 configuration covers whole-repository tasks and takes the three image IDs directly.

4. Authorize the two tool launches

Initialization writes an unsigned request naming the exact model and repository server commands, tool definitions, and configuration identities. The request grants no authority. Read it before you ask your provisioning system for signatures.

cat .session/provisioning-request.json

You should see source_commit, workspace_id, model_id, configuration_sha256, binary_sha256, and the installed environment inventory. For each of model and sandbox, compare argv, working_directory, execution_uid, execution_gid, tools, and request_timeout_seconds with the deployment you intend.

Keep argv an array: shell interpolation would change the requested command. Your provisioning system selects the migration stage, launch permissions, and trusted signing keys, signs the exact executable, argv, directory, UID/GID, and manifest, and returns authorization.json with the policy paths and independently pinned signer keys. The session command makes none of these trust decisions, and discovery adds no permission.

uv run python authorize-demo.py .session/provisioning-request.json local-policies
uv run chio-mini-swe session prepare --state .session \
  --authorization local-policies/authorization.json

Read more in Verified tool launch and signed manifest authority.

5. Prepare the host and run the agent

Copy operator/provider.example.json to provider.json and set your endpoint, model, and token prices. Export the API key under the variable it names; the trusted gateway reads it, and the coding worker never receives it.

uv run chio-mini-swe session prepare --state .session \
  --authorization authorization.json
uv run chio-mini-swe session run --state .session
uv run chio-mini-swe session status --state .session

You should see status report the session's state. Preparation creates the host with exactly two routes, model/model_infer and sandbox/execute. Every resume reuses the original task and plan, so an interrupted worker or host sends no new provider request or repository command while the original outcome is unknown.

6. Export the patch with its original receipts

uv run chio-mini-swe session result --state .session --out result

You should see result/repository/changes.patch beside the original receipts, the pinned kernel key, the repository baseline and final archives, and a verified transition report. Export works after the host stops, including after cancellation or expiry, and starts no model or repository server. Missing or altered evidence makes the command refuse instead of producing a best-effort patch.

7. Verify and apply the patch in a recipient checkout

Prepare recipient/ at the full commit you selected, set SELECTED_COMMIT to that revision, and obtain trusted-kernel.pub from the trusted operator before the bundle arrives. Repeat --source-path for each expected scope.

uv run chio-mini-swe-repository verify-export \
  --bundle result/repository --repository recipient \
  --revision "$SELECTED_COMMIT" --source-path package \
  --chio chio --kernel-key trusted-kernel.pub --server-id sandbox
git -C recipient apply --check ../result/repository/changes.patch
git -C recipient apply ../result/repository/changes.patch
git -C recipient diff -- package/
cd recipient/package
python3 -m unittest -v

You should see both addition tests pass in the patched checkout, while your source checkout still holds its dirty and untracked files. The recipient chose the commit, scope, and key independently of the bundle. Verification checks the signed action bindings and the ordered workspace transitions; the diff review and the tests judge the code.

{
  "model_calls": 3,
  "verified_transitions": 5,
  "verified_receipts": 8,
  "source_paths": [
    "package"
  ],
  "source_unchanged": true,
  "independent_recipient_checkout": true,
  "kernel_key_selected_before_export": true,
  "recipient_tests_passed": true,
  "wrong_recipient_key_refused": true,
  "completed_replay_did_no_new_model_work": true,
  "offline_combined_export": true
}

A verified run of this handoff recorded three model calls, five verified transitions, and eight verified receipts. The recipient key was selected at trusted initialization, before the bundle existed, and verification under a different key was refused. In the SDK, the Quickstart's fork.diff() and project.apply(fork.changes) make the same handoff inside one computer, and apply publishes only while main still equals the fork's base.

An interrupted session resumes from its last committed workspace

Every failure leaves the previous committed workspace authoritative and refuses to redispatch an unknown outcome. After you stop the host, session recover reconciles owned repository containers and partial command resources, then the same session continues.

• Worker exits after a known tool result. The original process call can replay; run the same session with the same task and operation IDs.
• Host dies after a command snapshot commit. The kernel outcome is known or unknown; inspect the original call and repository transition.
• Inference is interrupted. The provider outcome can stay unknown; stop, and never ask again under a new key.
• A command modifies files outside the scope. Snapshot publication is refused, and the previous committed workspace stays authoritative.
• Command container ownership is uncertain. Cleanup cannot be shown safe; stop the host, run recover, and keep mismatched resources.
• Export lacks a completed trajectory or matching evidence. No verifiable result bundle exists; keep the incomplete state and label nothing verified.

uv run chio-mini-swe session recover --state .session
uv run chio-mini-swe session run --state .session
uv run chio-mini-swe session result --state .session --out result

Recovery keeps the model stopped, keeps the original authority, and leaves the capability lifetime where it was. A command whose effect cannot be established stays stopped for operator resolution, so keep the state directory until its repository snapshots and original receipts have been inspected.

Exercise these failures without a provider account with the session and repository tests.

Session limits, provider, and launch fields

{
  "schema": "chio.mini-swe.provider.v1",
  "endpoint": "https://models.larkfield.example/v1",
  "model": "your-model",
  "credential_env": "CHIO_CODING_API_KEY",
  "timeout_seconds": 60,
  "input_usd_per_million": 0,
  "output_usd_per_million": 0,
  "max_output_tokens": 2048
}

{
  "schema": "chio.mini-swe.session-authorization.v1",
  "servers": {
    "model": {
      "launch_policy": "/private/policies/model.json",
      "launch_policy_signer": "PINNED_MODEL_SIGNER_HEX"
    },
    "sandbox": {
      "launch_policy": "/private/policies/sandbox.json",
      "launch_policy_signer": "PINNED_SANDBOX_SIGNER_HEX"
    }
  }
}

uv run python qualify_session.py --runtime-profile runtime.json \
  --output coding-session-evidence --scoped

uv run python qualify_repository.py --runtime-profile runtime.json \
  --output repository-failure-evidence

Next: run the same workflow on a Rust repository