Skip to content
spawnfile

Quickstart

Install

Section titled “Install”
Terminal window
npm install -g spawnfile

Verify:

Terminal window
spawnfile --version
spawnfile --help

Create an Agent

Section titled “Create an Agent”
Terminal window
spawnfile init

This creates a Spawnfile manifest and starter markdown docs in the current directory. The generated docs (SOUL.md, IDENTITY.md, AGENTS.md) are tailored to the selected runtime’s personality and capabilities:

my-agent/
|-- Spawnfile
|-- IDENTITY.md
|-- SOUL.md
\-- AGENTS.md

To scaffold for a specific runtime:

Terminal window
spawnfile init --runtime picoclaw

Edit the Spawnfile

Section titled “Edit the Spawnfile”

Open Spawnfile and set your agent’s name and runtime:

spawnfile_version: "0.1"
kind: agent
name: my-assistant
runtime:
  name: openclaw


workspace:
  docs:
    identity: IDENTITY.md
    soul: SOUL.md
    system: AGENTS.md


environment:
  env:
    LOG_LEVEL: info


execution:
  model:
    primary:
      provider: anthropic
      name: claude-sonnet-4-5
      auth:
        method: claude-code
  sandbox:
    mode: workspace

Write Your Agent’s Identity

Section titled “Write Your Agent’s Identity”

Edit the markdown docs:

  • SOUL.md — personality, voice, tone
  • IDENTITY.md — who the agent is, self-description
  • AGENTS.md — operating instructions and conventions

These are plain markdown files. The runtime loads them into the agent’s context.

Validate

Section titled “Validate”
Terminal window
spawnfile validate

This checks the manifest schema, file references, and graph structure without compiling.

View

Section titled “View”
Terminal window
spawnfile view .

This is read-only and writes no files while showing the resolved project graph.

Compile

Section titled “Compile”
Terminal window
spawnfile compile

The compiler emits runtime-native config and workspace files:

.spawn/
|-- runtimes/
|   \-- openclaw/
|       \-- agents/
|           \-- my-assistant/
|               |-- openclaw.json
|               \-- workspace/
|                   |-- IDENTITY.md
|                   |-- SOUL.md
|                   \-- AGENTS.md
\-- spawnfile-report.json

Check Status

Section titled “Check Status”
Terminal window
spawnfile status .

This reads the authored graph and the compile report without touching Docker, runtimes, or Moltnet. Use it to verify what Spawnfile sees before you run the agent.

Build and Run

Section titled “Build and Run”

Once compiled, you can build a Docker image and run it with auth:

Terminal window
spawnfile auth sync --profile dev --env-file .env
spawnfile build --tag my-assistant
spawnfile run --tag my-assistant --auth-profile dev --detach
spawnfile status . --live

Live status reads the detached deployment record, inspects the recorded Docker target, runs adapter-owned runtime probes, and checks Moltnet metadata without reading message bodies. See Docker Packaging for the full build and auth workflow, and Status for operational checks.

For Pi-backed orgs, the interactive loop is:

Terminal window
spawnfile dev up . --auth-profile dev --deployment dev
spawnfile dev apply . --agent new-agent --deployment dev

dev up writes to .spawn-dev by default. dev apply hot-loads one Pi agent and its Moltnet bridges into the running dev container without restarting the rest of the organization.

What’s Next

Section titled “What’s Next”