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 ENGINEERING_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 files/notes-roundtrip
runtime capability execute files/notes-roundtrip \
  --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 ENGINEERING_RUNTIME_CONSUMER=human

5. Shared company capabilities¶

Point at a version-controlled store without moving your Home:

export RUNTIME_CAPABILITIES_DIR=~/work/engineering-runtime-capabilities
runtime bootstrap
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 ENGINEERING_RUNTIME_HOME="$PWD/runtime-home"
export RUNTIME_CONFIG_FILE="$ENGINEERING_RUNTIME_HOME/config.yaml"
export RUNTIME_POLICY_FILE="$ENGINEERING_RUNTIME_HOME/policy-config.yaml"
export RUNTIME_GITHUB_TOKEN=ghp_…

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

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

7. Building from source (contributors)¶

Only needed if you are developing the binary itself:

git clone https://github.com/kishore-gutta/engineering-runtime.git
cd engineering-runtime
go build -o runtime .
./runtime version

Contributor setup lives in that repository's LOCAL_SETUP.md and docs/05-development/local-setup.md.

Next¶

Goal	Page
First capability	Quick Start
Change what is allowed	Policy
Point at another org	Runtime Context
Run the same thing in a pipeline	CI/CD
Let an AI drive `runtime` only	AI agent