A spec and compiler for autonomous agent runtimes. Write your agent once, compile for any runtime.
Spawnfile is a portable source format for autonomous agents and teams. You write one canonical project — identity docs, skills, MCP connections, model and sandbox intent, team structure, and declared communication surfaces — and spawnfile compile lowers it into the runtime-specific config and workspace each adapter needs.
It's not a runtime-to-runtime translator. The compiler starts from the canonical source, emits each declared adapter's output, and reports per-capability support as supported, degraded, or unsupported.
Pairs with Moltnet as the first provider for team.networks[], letting compiled agents share declared rooms, DMs, and history across runtimes without Spawnfile injecting its own message router.
npm install -g spawnfile
spawnfile --version
spawnfile --helpNode.js 22+ required. See source install for local development.
spawnfile init # scaffold an agent (defaults to openclaw)
spawnfile validate # check the graph
spawnfile view . # read-only graph view; writes no files
spawnfile compile # lower to runtime-native output
spawnfile status . # read declared/compiled status
spawnfile auth sync --profile dev --env-file .env
spawnfile build --tag my-agent # compile + docker build
spawnfile run --tag my-agent --auth-profile dev --detach
spawnfile status . --live # inspect the detached deployment
spawnfile publish . --tag you/my-agent:1.0.0 # compile + build + verify + pushCompiled output lands under .spawn/ by default, including a Dockerfile, entrypoint.sh, .env.example, and a prebuilt container/rootfs/ tree. spawnfile build uses the pinned runtime artifacts from runtimes.yaml; it does not rebuild runtimes from source.
spawnfile status is read-only. By default it shows authored and compiled state without Docker, runtime, or Moltnet calls. With --live, it reads the selected detached deployment record, inspects the recorded Docker target, runs adapter-owned runtime probes, and checks Moltnet metadata without reading message bodies. Add --logs for a redacted Docker log tail, or --watch to refresh status continuously.
Compiled images are self-describing: spawnfile publish pushes one to any OCI registry, and anyone can run it with no source — spawnfile up you/my-agent:1.0.0 --deployment prod --detach --auth-profile me — or inspect what it needs first with spawnfile status you/my-agent:1.0.0. See specs/DISTRIBUTION.md.
Declare external credentials in secrets: and provide values through an ignored env file or the shell environment. spawnfile auth sync --env-file .env stores declared model auth and project secrets in a local auth profile; spawnfile run --env-file .env can inject the same values directly for a single run. This is the intended pattern for credentials like GH_TOKEN, MCP tokens, and provider API keys.
A Spawnfile project is either an agent or a team.
Agent
my-agent/
├── Spawnfile
├── IDENTITY.md # who the agent is
├── SOUL.md # tone and personality
├── AGENTS.md # system prompt
├── MEMORY.md # long-lived memory
├── HEARTBEAT.md # periodic prompt for scheduled wakes
├── skills/
│ └── web_search/SKILL.md
└── subagents/
└── researcher/Spawnfile
Team
my-team/
├── Spawnfile
├── TEAM.md
├── shared/skills/...
└── agents/
├── orchestrator/Spawnfile
├── researcher/Spawnfile
└── writer/Spawnfile
Team members may target different runtimes; the compiler resolves each member independently. Subagents are internal helpers owned by a parent agent — not the same thing as team members. Team coordination is through shared declared agent surfaces and declared team networks, not a Spawnfile-owned router.
Not every file is required. Spawnfile names the portable roles; adapters decide how to lower them into runtime-native surfaces. See specs/SPEC.md for the full shape.
v0.1 targets autonomous agent runtimes that share a markdown workspace identity model.
| Runtime | Status | Default | Surfaces |
|---|---|---|---|
| OpenClaw | active | ✅ | Discord, Telegram, WhatsApp, Slack |
| PicoClaw | active | Discord, Telegram, Slack (WhatsApp blocked) | |
| NullClaw | exploratory | No active adapter yet | |
| ZeroClaw | exploratory | No active adapter yet | |
| OpenFang | exploratory | No active adapter yet | |
| Hermes Agent | exploratory | No active adapter yet | |
| OpenCode | exploratory | No active adapter yet |
Each adapter maps the portable schema into its native forms. The compiler reports a machine-readable spawnfile-report.json with the resolved graph, chosen runtimes, and capability outcomes (supported, degraded, unsupported). See specs/RUNTIMES.md for the live matrix and pinned versions, or runtimes.yaml for the registry source of truth.
Autonomous agent runtimes already share a meaningful core: markdown workspace identity, skill folders, MCP, model selection, sandboxing. Today that core is re-authored by hand for each runtime. Spawnfile makes it canonical so one source project can ship to any compatible runtime.
Hosted docs with rendered specs, runtime guides, and a capability matrix: spawnfile.com — start at Introduction, Quickstart, or the Runtimes overview.
The source-of-truth specs live in this repo:
specs/INDEX.md— map of all specsspecs/SPEC.md— canonical source formatspecs/COMPILER.md— compiler architecture and adapter contractspecs/CONTAINERS.md— container compilationspecs/RUNTIMES.md— runtime registry and version pinningspecs/SURFACES.md— messaging surface modelspecs/STATUS.md— static and live operational statusspecs/DISTRIBUTION.md— image distribution, publish, and sourceless runfixtures/— canonical example projects
git clone https://github.com/noopolis/spawnfile.git
cd spawnfile
nvm use
npm install
npm run build
npm linkTo clone pinned runtimes and generate reference blueprints:
npm run runtimes:syncFor local development without linking globally:
npm run dev -- validate fixtures/single-agentSee CONTRIBUTING.md for local setup, tests, and the runtime adapter contract.
MIT — see LICENSE.