Adding a Runtime

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

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
  install:
    kind: npm
    package: myruntime
    version: 1.0.0
  status: exploratory

The install block is the compiled install surface Spawnfile will use when it builds containers. Exploratory runtimes can start without a verified install strategy, but active runtimes intended for spawnfile build should declare one in runtimes.yaml.

2. Research

Study the pinned upstream source and its config format. Capture a frozen reference layout under blueprints/<name>/ when the runtime exposes a declarative configuration surface, then document findings in specs/research/RUNTIME-NOTES.md.

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

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

5. Test

Write tests in src/runtime/myruntime/adapter.test.ts. Verify output matches the blueprint, the generated container can install the pinned runtime, and any host-reachable service has a smoke check.

6. Promote

Once tests pass, the adapter produces valid output, and the build/install smoke path works, change status to active in runtimes.yaml.