Local Setup (Human)¶

Run Engineering Runtime on a laptop or workstation. No Go toolchain, no source checkout, and no cloud CLI are required for the core path — only the runtime binary.

For the shortest path, use Quick Start. This page is the fuller local contract: home layout, env vars, day-to-day commands, and a throwaway sandbox.

1. Install the binary¶

Follow Installation for macOS, Linux, or Windows. Confirm:

runtime version
runtime bootstrap
runtime config validate

2. Runtime Home¶

Default location:

OS	Path
macOS / Linux	`~/.engineering-runtime`
Windows	`%USERPROFILE%\.engineering-runtime`

Relocate for a project or experiment:

export RUNTIME_HOME=/tmp/runtime-home
runtime bootstrap

Full layout and ownership rules: Runtime Home.

3. Authenticate¶

The runtime never stores credentials. Export or log in with the platform, then validate:

export RUNTIME_GITHUB_TOKEN=ghp_…     # GitHub PAT
runtime auth status
runtime auth login github             # optional explicit check

CLI-native platforms (GCP, Kubernetes, OpenShift) use their own login, then an authentication.<provider> block in config.yaml. See Authentication.

4. Day-to-day usage¶

Provider operations

runtime files write ./notes.txt hello
runtime github user get
runtime github repo view cli/cli
runtime github --help                 # live surface for this binary

Command Engine (allowed binaries only)

runtime command run git status
runtime command run gh repo list --limit 5
runtime command run kubectl get pods

Capabilities

runtime capability validate ~/work/engineering-runtime-capabilities/capabilities/files/notes-roundtrip.md
runtime capability execute ~/work/engineering-runtime-capabilities/capabilities/files/notes-roundtrip.md \
  --input path=./hello.txt --input message="local run"

Discover contracts (refreshed with the binary)

ls ~/.engineering-runtime/commands/
cat ~/.engineering-runtime/commands/github_commands.txt
ls ~/.engineering-runtime/specs/

Audit

runtime audit tail -n 20
runtime audit tail --output json

Mark interactive sessions on the audit trail:

export RUNTIME_CONSUMER=human

5. Shared company capabilities¶

Clone a version-controlled store at a reviewed revision and declare its capabilities/ directory under capabilities.sources:

runtime capability execute github/github-repo-health \
  --input repository=cli/cli

See Sharing a Capability Directory and the engineering-runtime-capabilities repo.

6. Throwaway sandbox (upgrade / experiment)¶

Same pattern CI uses — isolate Home so you never touch your real config:

export RUNTIME_HOME="$PWD/runtime-home"
export RUNTIME_GITHUB_TOKEN=ghp_…

rm -rf "$RUNTIME_HOME"
runtime bootstrap
runtime config validate

Wipe and re-bootstrap after swapping binary versions to test upgrades. See Upgrading.

Next¶

Goal	Page
First capability	Quick Start
Change what is allowed	Policy
Understand or select a native-tool target	Where operations run
Run the same thing in a pipeline	CI/CD
Let an AI drive `runtime` only	AI agent

Operational examples on this site were verified against Runtime 0.9.8. After bootstrap, the version-exact files in Runtime Home win.