Skip to content

Set Up Your Workspace

Goal. Go from a fresh install to a working setup that can run a files capability, reach GitHub, and refuse anything outside what you granted.

Time. About five minutes, most of it creating a token.

You need. The Runtime installed, and a GitHub account if you want the GitHub half.

Every command on this page was run against the release this site documents, from an empty home directory, in the order shown.

1. Create the workspace

Governance documents live outside the Runtime Home. Runtime refuses to write them inside it, so it is never ambiguous who owns what governs execution.

mkdir -p ~/er/home ~/er/work ~/er/capabilities
Directory Holds
~/er/home Runtime's own state — specs, commands, cache, logs
~/er/work Where capabilities are allowed to read and write
~/er/capabilities Your capability files

2. Generate config and policy

Generate them from the binary rather than writing them by hand — the samples match the schema the installed version actually parses.

export RUNTIME_HOME=~/er/home

runtime config init config --output ~/er/config.yaml
runtime config init policy --output ~/er/policy.yaml

Wrote 3011 bytes to ~/er/config.yaml
Wrote 8554 bytes to ~/er/policy.yaml

Each also prints the environment variable that puts it in force. Nothing reads either file until you set them, which is step 4.

3. Grant file access

File access is default-deny. A fresh policy grants nothing, and files read fails until a directory is named. Open ~/er/policy.yaml and set the roots:

file_policy:
  read_roots:
    - "/Users/you/er/work"
  write_roots:
    - "/Users/you/er/work"

Use absolute paths

The shipped sample uses ".", which is resolved against your current working directory — the grant moves with wherever you happen to be standing. The same command then succeeds in one directory and is denied in another. Write the path out in full.

Read and write are separate grants; one does not imply the other. Granting read widely is cheap, but keep write narrow — a capability that can write into a git checkout can rewrite tracked source with nobody reviewing it, and a root covers everything beneath it, so a home directory grant includes ~/.ssh and your shell profile.

See choosing roots for the full guidance, and budgets for what max_read_bytes and friends actually do.

4. Put it all in force

Add these to ~/.zshrc or ~/.bashrc so they survive a new terminal:

export RUNTIME_HOME=~/er/home
export RUNTIME_CONFIG_FILE=~/er/config.yaml
export RUNTIME_POLICY_FILE=~/er/policy.yaml
export RUNTIME_CAPABILITIES_DIR=~/er/capabilities

Then confirm what is actually in force — not what you think you set:

runtime config validate

Config:   ~/er/config.yaml (explicit override (RUNTIME_CONFIG_FILE))
Policy:   ~/er/policy.yaml (explicit override (RUNTIME_POLICY_FILE))
Safety:   compiled-safety-profile/v3 — invariants no document can disable

If a change seems ignored

Exports only apply to shells started after you added them. Run source ~/.zshrc or open a new tab. A stale value here produces confusing errors — pointing RUNTIME_POLICY_FILE at a config file, for example, fails with field runtime not found in type policy.Policy.

5. Add your GitHub token

Skip this if you only want local file capabilities.

Create a personal access token — classic or fine-grained. For read-only listing, repo scope (or public_repo for public repositories only) is enough. See Connect GitHub for what each operation needs.

export RUNTIME_GITHUB_TOKEN=ghp_your_token_here

The token goes in the environment, never in a file. config.yaml only names which variable to read:

authentication:
  github:
    enabled: true
    base_url: https://api.github.com   # GitHub Enterprise Server? point it here
    token_env: RUNTIME_GITHUB_TOKEN

Verify:

runtime auth status
# github     ✓ subject=your-username token=ghp_...

6. Run something

A local file capability. Save as ~/er/capabilities/hello-notes.md:

# Hello notes

```runtime
version: v1

inputs:
  path:
    description: File to write, inside a granted write root
    required: true
  message:
    description: Text to write
    required: true

workflow:
  - provider: files
    args: [write, "${path}", "${message}"]

  - provider: files
    args: [read, "${path}"]
```

runtime capability validate hello-notes
runtime capability execute hello-notes \
  --input path=~/er/work/hello.txt \
  --input message="it works"

Step 1: files write
  Message:  wrote 8 bytes to hello.txt
Step 2: files read
  Message:  read 8 bytes from hello.txt
  it works

Inputs are passed with --input key=value, repeated per input. capability execute takes exactly one positional argument — the capability name.

GitHub, directly.

runtime github user get          # who am I
runtime github repo list         # my own repositories
runtime github repo list my-org  # an organisation's repositories

repo list <arg> expects an organisation

The optional argument is an org, not a username. Passing your own username looks up an organisation that does not exist and returns 404. Omit the argument for your own repositories, or use runtime github api GET /users/<username>/repos for another user's.

7. Confirm the boundary holds

A setup that only proves the happy path has not been tested. Write outside the granted root:

runtime files write /tmp/nope.txt x

files write /tmp/nope.txt is outside every directory policy grants write
authority to (/Users/you/er/work). The path is not evaluated against a
pattern — it has to resolve inside a granted root, so `..` and an absolute
path elsewhere reach nothing

That refusal is the product working. It is also recorded — denials are audited exactly like successes:

runtime audit tail

Failures you may hit

Symptom Cause Fix
field runtime not found in type policy.Policy RUNTIME_POLICY_FILE points at a config file Correct the variable, then reload the shell
needs read authority and the policy in force grants it nowhere No read_roots Step 3
Works in one directory, denied in another A relative root such as "." Use absolute paths
404 from repo list <name> That is a user, not an org Omit the argument, or use github api
Changes seem ignored Exports not loaded in this shell source ~/.zshrc, or open a new tab
declarative_policy_digest is not a 64-character hex digest A stale signed enterprise generation in the Home Re-sign it, or move <Home>/enterprise/ aside

Next

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