OpenShell Agent Runner

openshell-agent-runner provides the oar CLI for launching an ephemeral agent to accomplish one configured task. Each oar run creates an isolated OpenShell sandbox, runs the task, publishes one result, and removes the sandbox. This single-task lifecycle makes OAR a natural fit for CI jobs and other automated workflows that need bounded agent execution.

OAR has four commands:

oar init PROFILE_ROOT --model MODEL_ID [OPTIONS]
oar validate PROFILE_DIRECTORY
oar run PROFILE_DIRECTORY --task TASK --output PATH [OPTIONS]
oar doctor [OPTIONS]

The profile defines what the ephemeral agent can see and do. OAR uploads the declared inputs, starts Pi for the selected task, captures its result, optionally validates it against a configured JSON Schema, publishes it atomically, and deletes the sandbox. Repository inspection, Git operations, and conclusions belong to Pi inside the sandbox.

Why OAR fits CI

• Each invocation has a bounded lifecycle: one task, one ephemeral sandbox, one result, then cleanup.
• Profiles can be versioned with the repository so agent behavior, permissions, model settings, and output contracts are reviewable inputs to the job.
• Stable exit codes and an explicit --output path let later CI steps consume the result or fail the job.

The CI worker must be able to reach an existing OpenShell gateway with an inference route for the profile's model. OAR uses that configured runtime; it does not provision providers or credentials.

Documentation

• Launch ephemeral agents with OAR: install, run a starter task, and understand the execution lifecycle.

Requirements

• uv.
• OpenShell 0.0.111 or newer.
• A running OpenShell gateway that the host can reach.
• An inference route and its model ID.

OAR uses the gateway's default workspace unless --workspace selects another one. An OpenShell workspace is a gateway-side namespace for sandboxes, inference routes, and access controls; it is not the /workspace directory inside a sandbox.

Quick start

Create every profile packaged with OAR, check the gateway, and preview the starter review task:

export MODEL_ID="provider/model"

uvx --from openshell-agent-runner oar init ./profiles \
  --model "$MODEL_ID"
uvx --from openshell-agent-runner oar doctor --gateway openshell
uvx --from openshell-agent-runner oar validate ./profiles/reviewer
uvx --from openshell-agent-runner oar run ./profiles/reviewer \
  --task review \
  --gateway openshell \
  --input document.md \
  --output review.md \
  --dry-run

Replace provider/model with the model ID configured on your inference route and openshell with your gateway name. Remove --dry-run after doctor confirms that the gateway and route are ready.

init copies packaged profiles into an ordinary local directory so they can be inspected, edited, and committed. Omit --profile to create all packaged profiles, or select one or more explicitly:

uvx --from openshell-agent-runner oar init ./profiles \
  --profile reviewer \
  --model "$MODEL_ID" \
  --thinking high

The openshell Pi provider, managed inference URL, and non-secret adapter value are generated by OAR. MODEL_ID is only a shell variable passed to the required --model option; OAR does not read it implicitly. Pass --thinking off when the selected model does not support reasoning.

Development install

Directly from this checkout:

uvx --from ./projects/openshell-agent-runner oar --help

For an editable development environment:

uv sync --project projects/openshell-agent-runner --locked
uv run --project projects/openshell-agent-runner pre-commit install
uv run --project projects/openshell-agent-runner oar --help

The pre-commit hook automatically applies Ruff's Black-compatible formatter to staged Python files in this project. Hook installation is required once per checkout.

See the release instructions for package publication. The release command builds and publishes only openshell-agent-runner; it does not package other projects in this repository.

OAR consumes existing OpenShell state and never creates or changes gateways, providers, workspaces, or inference routes.

Validate a profile

Pass the profile directory containing profile.yaml:

uv run --project projects/openshell-agent-runner oar validate \
  ./profiles/reviewer

Validation loads every referenced prompt, policy, skill, extension, and optional output schema; rejects unknown keys and path escapes; and checks each schema.

Check OpenShell

doctor performs read-only checks of the OpenShell CLI, selected gateway, and inference configuration:

uv run --project projects/openshell-agent-runner oar doctor \
  --gateway openshell

Run a profile task

Show help for a specific task by placing its profile and task before --help:

uv run --project projects/openshell-agent-runner oar run \
  ./profiles/reviewer \
  --task review \
  --help

This prints focused task help from the executable profile and task configuration: the invocation, configured uploads and environment, and the resulting output. Generic CLI options remain in oar run --help.

uv run --project projects/openshell-agent-runner oar run \
  .github/openshell-agents/profiles/dev-note-reviewer \
  --task editorial \
  --gateway openshell \
  --upload .:/workspace/source \
  --upload .git:/workspace/source/.git \
  --env REVIEW_TARGET_PATH=docs/dev-notes/posts/2026-08-07-formal-methods-ai-generated-robot-actions.md \
  --output /tmp/dev-note-review.json

The supported run options are deliberately small:

• --task: task identifier from the profile.
• --output: host destination for the agent result.
• --input: host document required by tasks declaring required_input: document.
• --upload: repeatable native OpenShell SOURCE:DESTINATION mapping.
• --env: repeatable non-secret KEY=VALUE sandbox environment value. Keys use shell identifier syntax; OpenShell reserves the OPENSHELL_ prefix.
• --gateway: select an existing OpenShell gateway.
• --workspace: select a gateway-side OpenShell namespace. It defaults to default and is unrelated to the sandbox's /workspace directory.
• --timeout-seconds: maximum agent runtime.
• --keep-sandbox: retain the sandbox for deliberate debugging.
• --dry-run: print the complete command sequence and host actions without executing anything.

A source can be a file or directory. For native file uploads, the destination is the exact filename; for directory uploads, it is the destination directory. OAR does not add repository, snapshot, changed-file, or Git abstractions. The first upload above uses OpenShell's default Git-aware filtering, while the explicit .git upload provides repository history without also uploading every ignored file. Review upload contents before sending private source to a remote gateway. OAR always preserves OpenShell's Git-aware filtering; upload an ignored file explicitly when a task genuinely needs it.

Inspect the execution

Add --dry-run to the same run invocation:

uv run --project projects/openshell-agent-runner oar run \
  .github/openshell-agents/profiles/dev-note-reviewer \
  --task editorial \
  --gateway openshell \
  --upload .:/workspace/source \
  --upload .git:/workspace/source/.git \
  --env REVIEW_TARGET_PATH=docs/dev-notes/posts/2026-08-07-formal-methods-ai-generated-robot-actions.md \
  --output /tmp/dev-note-review.json \
  --dry-run

The preview prints the exact dynamically generated openshell sandbox create, download, ownership get, and delete commands in execution order. It also shows host-side result validation and atomic publication. Temporary paths, sandbox identity, and the ownership token are generated exactly as they are for a real run, but no subprocess or sandbox operation is executed.

Profile format

A profile contains only settings that can change model behavior, sandbox permissions, inputs, or task execution:

id: reviewer
description: Review an uploaded document.

sandbox:
  policy: policy.yaml
  upload: []
  env: []

tasks:
  review:
    required_input: document
    prompt: prompt.md
    tools: [read, grep, find, ls, bash]
    skills: []
    extensions: []

Each profile directory must contain profile.yaml, models.json, and settings.json. Profile-owned paths resolve relative to that directory. Native upload sources retain OpenShell's current-directory semantics.

models.json is Pi's native provider and model registry. OAR requires exactly one provider named openshell and exactly one model. settings.json is Pi's native runtime selection and must set defaultProvider, defaultModel, and defaultThinkingLevel. OAR copies both files unchanged and passes that same selection explicitly as --provider, --model, and --thinking, so every task uses one visible runtime configuration. Never place real credentials in these files; OpenShell supplies inference access.

Profiles created by oar init use this minimal Pi model configuration:

{
  "providers": {
    "openshell": {
      "baseUrl": "https://inference.local/v1",
      "api": "openai-completions",
      "apiKey": "unused",
      "authHeader": true,
      "compat": {
        "supportsDeveloperRole": false
      },
      "models": [
        {
          "id": "provider/model",
          "reasoning": true
        }
      ]
    }
  }
}

The matching runtime selection is:

{
  "defaultProvider": "openshell",
  "defaultModel": "provider/model",
  "defaultThinkingLevel": "high"
}

Pi supplies conservative defaults for omitted model capabilities. oar init sets reasoning from the selected thinking level and retains the compatibility override required by the OpenAI-compatible route. Add explicit model behavior to the initialized profile when the selected route needs it.

Result protocol

By default, OAR captures Pi's final headless response and publishes it without interpreting its contents. The result must exist, be non-empty, and fit within the one-MiB transport limit. OAR applies that limit to the download process and checks the downloaded file again before publication.

A task can optionally require structured JSON by referencing a JSON Schema:

tasks:
  review:
    prompt: prompt.md
    output_schema: schemas/review.json
    tools: [read, grep, find, ls, bash]

OAR uploads the schema and automatically enables the generic submit_result tool. Invalid submissions return schema diagnostics to Pi so it can correct and resubmit within the same session. OAR validates the accepted JSON against the same Draft 2020-12 schema again before publishing it. Pi's tool parameters use TypeBox, as required by its extension API, while the submitted result is validated with Ajv. The schema and its domain concepts belong entirely to the profile; OAR has no built-in review result type. JSON Schema extension keywords and format values are treated as annotations rather than additional validation rules on both sides. OAR rejects pattern and patternProperties because Python and JavaScript use different regular-expression dialects; use enum, const, length, and numeric constraints for portable validation.

OAR fixes implementation details that do not change the intended result: Pi is the harness, its image is bundled with the package, autonomous approval and provider isolation are enabled, the result is written to a standard sandbox path, and the result size guard is one MiB.

The package includes a repository-neutral reviewer profile. Run oar init to create an editable local copy. Its review task requires --input DOCUMENT and uploads that file to OAR's standard document location in the sandbox.

Image contract

The runner packages the Pi image context, pins the tested Pi version, and installs the read-only harness under /opt/oar. OAR passes that packaged context to native openshell sandbox create; profiles do not select an image. This keeps the harness implementation and image contract in one release unit.

Security boundary

• Pi runs as the image's unprivileged user under the profile policy.
• Caller uploads under /workspace and generated resources under /sandbox/oar-runtime are writable because OpenShell performs uploads through the workload policy.
• /sandbox/oar-runtime and /sandbox/artifacts are reserved for the runner; profile and command-line uploads cannot write there.
• Source changes are disposable and are never synchronized back.
• Only OAR's standard result path is downloaded.
• Host-side transport checks, optional JSON Schema validation, and atomic publication are the result acceptance boundary.
• Result claims and provenance remain agent-produced; schema validation does not independently prove their factual accuracy.
• --env is for non-secret values. Credentials remain in OpenShell's provider and inference mechanisms.
• Cleanup checks a reserved ownership label before deleting the sandbox.

The supplied Dev Note policy permits no ordinary network egress. Inference uses OpenShell's managed inference path.

Exit codes

Code	Meaning
0	Execution completed and the output validated.
1	OpenShell execution, timeout, missing remote output, download size limit, ownership inspection, or cleanup failed.
2	CLI input or profile configuration was invalid.
3	A downloaded output was empty, invalid, or failed its contract.

Development

Run from projects/openshell-agent-runner:

uv sync --locked
uv run ruff format --check .
uv run ruff check .
uv run ty check
uv run pytest
uv build

The repository workflow validates the repository and starter profiles, runs the credential-free suite, builds the distributions, verifies the wheel contents, and builds the Pi image. Real inference requires an authenticated OpenShell gateway and is intentionally not run on GitHub-hosted workers.