Quickstart

Install

npm install -g spawnfile

Verify:

spawnfile --version
spawnfile --help

Create an Agent

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:

spawnfile init --runtime tinyclaw

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

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

spawnfile validate

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

View

spawnfile view .

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

Compile

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

Build and Run

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

spawnfile auth sync --profile dev --env-file .env
spawnfile build --tag my-assistant
spawnfile run --tag my-assistant --auth-profile dev

See Docker Packaging for the full build and auth workflow.

What’s Next

• Write a Spawnfile — full manifest reference
• Agent Docs — understand document roles
• Skills & MCP — add skills and tool connections
• Teams — define multi-agent teams
• Compiling — understand the compile pipeline
• Docker Packaging — build and run containers with auth