Harness is a declarative runner for OpenShell.
A repository checks in workflow documents describing repository automation or a
developer session. The same workflow can run from GitHub Actions, another CI
system, or a local terminal with --attach. Harness resolves the document,
runs it in an isolated OpenShell sandbox, returns the result, and cleans up the
run.
Its purpose is to remove repeated gateway, credential, policy, sandbox-lifecycle, and CI plumbing from repository workflows. Each workflow can combine a target, provider references, policies, skills, an agent, and an inference route for a specific use case. The repository still owns task behavior, prompts, review criteria, source checkout, and result handling.
Harness is not a second OpenShell, provider manager, credential store, policy
language, scheduler, controller, or release manager. The closest operational
model is submitting a Kubernetes Job: plan previews a run and apply runs
one. There is no Harness database, release history, rollback, or watch loop.
The workflow file is a desired input document, not a stored Harness resource:
version: 1
name: pr-review
target:
gateway: acs
workspace: stackrox
sandbox:
image: quay.io/example/reviewer:v1
providers: [github-review]
policy:
file: review-policy.yaml
payloads:
- source: .github/skills/pr-review/SKILL.md
destination: /sandbox/skills/pr-review/SKILL.md
outputs:
- source: /sandbox/artifacts
destination: artifacts
required: false
source:
repo: https://github.com/stackrox/stackrox
ref: main
destination: /sandbox/stackrox
agent:
type: claude
args: [--print, "Review the supplied repository input"]The document can declare a gateway/workspace target, an inference route, sandbox provider attachments, sandbox image/policy/environment, agent command, source checkout, payload files, and paths to download after execution. Provider credentials and permissions remain OpenShell-owned. Changing the target or policy lets the same repository workflow run with a different trust boundary.
The one-shot lifecycle is:
load and validate YAML
→ resolve flags, environment, and defaults
→ read gateway state and build a plan
→ verify references and reconcile compatibility settings
→ create, run, and observe the sandbox
→ return the result and clean up
The current inference-route write is a compatibility bridge for gateways that do not yet own that configuration natively. It requires workspace-admin access when the route differs and should be used only with an isolated or explicitly administered workspace. Prefer a bootstrap-owned matching route for shared workspaces; this bridge should shrink as OpenShell does.
Install the OpenShell version in .openshell-version, then select a gateway
using the native CLI or target a configured HyperShell gateway:
make openshell
openshell gateway add https://127.0.0.1:17670 --local --name openshell
openshell gateway select openshell
harness workflow plan workflow.yaml
harness workflow apply workflow.yaml
harness workflow apply workflow.yaml --attach--attach runs the same workflow with your terminal connected to the declared
agent command. It does not open a host shell or bypass the workflow policy.
For post-run debugging, set sandbox.keep: true and use native OpenShell
commands such as:
openshell sandbox connect <name>
openshell sandbox exec <name> -- <command>
openshell sandbox logs <name>
openshell sandbox delete <name>Harness owns no durable workflow state. OpenShell or the platform owns gateway registrations, workspaces, providers, inference routes, credential material, policies, and sandboxes. GitHub Actions owns workflow-run state, labels, artifacts, concurrency, and approvals. A host-side source cache and an explicit result file are outputs or performance optimizations, not workflow state.
Resolution order for gateway and workspace targets is:
- explicit flags (
--gateway,--workspace); OPENSHELL_*environment variables;- the workflow target;
- the active/default OpenShell gateway.
${VAR} references in workflow strings are expanded from the calling process
environment. Harness does not implicitly load .env files; source one in the
calling shell or configure the values in CI. Defaults include workspace
default, inference route inference.local, and the NVIDIA OpenShell
community base image. HARNESS_OS_IMAGE is an explicit local or integration
testing override: it takes precedence over both a workflow-selected image and
the default image for harness plan and harness apply. Unset it when the
workflow should select its own published StackRox image or use the default.
The workflow file, policy file, and payload declarations are trusted host-side inputs. A workflow can intentionally interpolate host environment values or upload readable host files, so do not run an untrusted PR-supplied workflow in a credentialed host context. The trusted PR-review path checks out workflow code from the caller's default branch and stages the pull-request diff only as data.
Direct OIDC target registration in a workflow is in-memory for that invocation.
The OIDC client secret is read from OPENSHELL_OIDC_CLIENT_SECRET and is never
part of the workflow document.
Harness does not create, update, or delete providers or credentials. A platform
administrator or trusted OpenShell bootstrap provisions them in the target
HyperShell workspace, for example with the native openshell provider create
flow. A workflow names providers where they are used: inference.provider
selects the inference provider and sandbox.providers attaches masked provider
proxies to the new sandbox. plan and apply verify those references before
execution.
If a referenced provider is absent, apply fails before creating the sandbox.
The gateway keeps the provider credential and exposes only its masked proxy
interface inside the sandbox. The runner's own gateway credential—local
OpenShell login, OIDC service account, or mTLS—is separate and is used only to
connect and create the sandbox; it is not automatically a sandbox provider.
The PR-review demo currently has a trusted shell bootstrap that creates temporary providers for its self-contained test path. That is adapter-specific bootstrap, not Harness workflow behavior. A HyperShell deployment should move those providers to platform bootstrap and let the workflow reference the pre-provisioned names.
Workflow files contain provider names, not credentials. OpenShell resolves the
provider and exposes a proxy-backed, masked interface to authorized sandbox
requests. Raw credentials must not appear in workflow YAML, sandbox.env,
payloads, agent arguments, logs, artifacts, prompts, or structured JSON/YAML
output. Use provider configuration and OpenShell policy to grant capabilities;
provider attachment alone does not authorize comments, pushes, labels, or merges.
This is a contract for trusted workflow authors and bootstrap code, not a secret scanner for arbitrary YAML. Interpolated values are redacted from resolved configuration, plan, and dry-run display output, but the runner cannot infer whether a literal host value is a credential.
For GitHub Actions, trusted host-side setup mints a short-lived installation
token from the repository's OpenShell GitHub App and uses it to register the
native OpenShell GitHub provider. The token is not placed in the sandbox
environment or agent payload. Configure OPENSHELL_GITHUB_APP_CLIENT_ID as a
repository variable and OPENSHELL_GITHUB_APP_PRIVATE_KEY as a repository
secret. The installed App must have repository permissions Contents: read and
Pull requests: read and write, and must be installed on the target repository.
See docs/ci.md for the bootstrap and secret contract.
The reusable PR reviewer is the first supported workflow archetype:
pr-reviewer-with-comments. The consuming repository supplies its skill and
review criteria; Harness supplies the execution boundary. The same runner can
also execute repository maintenance, CI assistance, research, or interactive
developer workflows when those workflows define the appropriate policy and
provider boundary.
jobs:
ai-review:
uses: stackrox/harness-openshell/.github/workflows/pr-review-reusable.yml@<harness-sha>
with:
harness-ref: <same-40-character-harness-sha>
skill-path: .github/skills/pr-review/SKILL.md
allow-draft-reviews: false
openshell-github-app-client-id: ${{ vars.OPENSHELL_GITHUB_APP_CLIENT_ID }}
secrets:
VERTEX_AI_SERVICE_ACCOUNT_KEY: ${{ secrets.VERTEX_AI_SERVICE_ACCOUNT_KEY }}
OPENSHELL_GITHUB_APP_PRIVATE_KEY: ${{ secrets.OPENSHELL_GITHUB_APP_PRIVATE_KEY }}Use pull_request_target when the workflow needs secrets or write permissions;
the called workflow reads trusted files from the caller’s default branch and
stages the pull-request diff as data. The ai-review label is explicit opt-in
and is not added automatically. A pull_request trigger is appropriate only
for a credential-free demonstration.
Future archetypes such as issue triage, issue-to-PR, security review, or auto-merge require separate mutation and approval contracts; they are not implicitly enabled by the runner.
| Command | Purpose |
|---|---|
harness workflow plan FILE |
Render a read-only plan |
harness workflow apply FILE |
Run the workflow headlessly |
harness workflow apply FILE --attach |
Run it with an interactive terminal |
harness workflow apply FILE --output-dir DIR |
Download declared workflow outputs below DIR |
harness workflow apply FILE --setup-only |
Verify references and configure inference without running a sandbox |
Plan and dry-run output support -o table, -o json, and -o yaml; credential
values are never serialized. harness workflow apply FILE -o json or -o yaml
prints the resolved, redacted configuration without executing; use
--result-file result.json for an execution result. The Harness CLI deliberately has no doctor,
init, delete, get, or describe commands. Use native OpenShell commands
for gateway health, sandbox inspection, and retained-sandbox deletion. Normal
apply cleanup deletes a sandbox by default; set sandbox.keep: true only to
retain it for debugging.
- AGENTS.md — architecture constraints and validation matrix
- docs/workflow-format.md — version 1 workflow contract
- docs/ci.md — trusted CI bootstrap and credential contract
- docs/compatibility.md — tested OpenShell, ACP, and Go versions
- examples/github-pr-reviewer/ — workflow inputs and policy
Fast checks:
make test
make test-suiteGateway lifecycle checks are available through make test-local, make test-kind,
and make test-remote. Provider-capability checks require platform-provisioned
credentials.