Skip to content
spawnfile

Adding a Runtime

Requirements

Section titled “Requirements”

A Spawnfile-compatible runtime must:

  1. Run as a long-lived service or daemon
  2. Use a markdown workspace as a first-class agent surface
  3. Expose a declarative config surface the compiler can emit to

Steps

Section titled “Steps”

1. Add to the Registry

Section titled “1. Add to the Registry”

Add an entry to runtimes.yaml with status: exploratory:

myruntime:
  remote: [email protected]:org/myruntime.git
  ref: v1.0.0
  default_branch: main
  status: exploratory

2. Research

Section titled “2. Research”

Clone the runtime and study its config format:

Terminal window
./scripts/runtimes.sh myruntime
./scripts/blueprints.sh myruntime

Document findings in specs/research/RUNTIME-NOTES.md.

3. Build the Adapter

Section titled “3. Build the Adapter”

Create src/runtime/myruntime/adapter.ts implementing the RuntimeAdapter interface:

  • compileAgent(node) — emit runtime-native config and workspace files
  • compileTeam(node) — optional, for runtimes with native team support
  • validateRuntimeOptions(options) — optional, validate runtime-specific options

4. Register

Section titled “4. Register”

Add the adapter to src/runtime/registry.ts.

5. Test

Section titled “5. Test”

Write tests in src/runtime/myruntime/adapter.test.ts. Verify output matches the blueprint.

6. Promote

Section titled “6. Promote”

Once tests pass and the adapter produces valid output, change status to active in runtimes.yaml.