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 --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 auth sync --profile dev --env-file .env
spawnfile build --tag my-agent # compile + docker build
spawnfile run --tag my-agent --auth-profile devCompiled 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.
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) | |
| TinyClaw | active | Discord, Telegram, WhatsApp (pairing-gated) | |
| NullClaw | exploratory | No active adapter yet | |
| ZeroClaw | 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 modelfixtures/— 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.