From 6f4e196336721d0be49a8ed21250a838d9db0072 Mon Sep 17 00:00:00 2001 From: Juan Cruz Fortunatti Date: Sat, 12 Sep 2026 13:48:46 +0200 Subject: [PATCH 1/2] docs: simplify README around a verified starter --- README.md | 272 ++++++++++++------------------------------------------ 1 file changed, 59 insertions(+), 213 deletions(-) diff --git a/README.md b/README.md index ad1fc7c..58e45fd 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,11 @@ # Spawnfile -> A spec and compiler for autonomous agent runtimes. Write your agent once, compile for any runtime. +> An agent team you can keep in Git.

npm downloads - node + node MIT website

@@ -14,249 +14,95 @@ Spawnfile compiles one agent source into multiple runtimes

-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. +Describe your agents, give them identities and tools, and keep the whole team in one source project. Spawnfile compiles that project into the configuration and workspaces their runtimes need, then builds and deploys it with Docker. -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**](https://moltnet.dev) 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. - -For a Simfile linked to a Spawnfile, the product entrypoint is owned by -Simfile: - -```bash -simfile run ./Simfile --view -``` - -That command delegates only organization lifecycle operations to Spawnfile's -public CLI and versioned receipts. Spawnfile prepares target resources, -deploys the organization, records the pinned Pi-bridge Moltnet identity, -exports evidence, and cleans up; it does not carry simulation behavior or -trigger cognition. The world reaches paused/pristine readiness first, the -organization starts second, and one attested activation releases independent -world ticks and organization-owned schedules. A separately manifested -`simfile.world-decision-claim.v1` capability may extend the base world-sidecar -ABI without changing it. See -[`specs/ECOSYSTEM_RUNTIME_BOUNDARIES.md`](specs/ECOSYSTEM_RUNTIME_BOUNDARIES.md) -for ownership and [`specs/TARGETS.md`](specs/TARGETS.md) for target, auth, -Moltnet pinning, recovery, and cleanup contracts. - -## Install - -```bash -npm install -g spawnfile -spawnfile --version -spawnfile --help -``` - -Node.js 22+ required. See [source install](#from-source) for local development. - -## The happy path - -```bash -spawnfile init # scaffold an agent (defaults to openclaw) -spawnfile init --list-templates # list bundled example templates -spawnfile init --template mixed-runtime-org # scaffold from an example org -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 up . --context gpu-host --detach # build and run on a Docker context -spawnfile dev up . --auth-profile dev # detached dev loop in .spawn-dev -spawnfile dev apply . --agent researcher # hot-add/reload one Pi agent -spawnfile dev activity . --agent researcher # inspect buffered Pi activity events -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 + push -``` - -Compiled 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. Daimon, OpenClaw, and PicoClaw use published copyable artifact images by default, so normal prompt/config edits reuse their dependency layers. Daimon accepts its production manifest/receipt pins or an explicitly supplied generated non-production identity for the fixed loopback registry; raw, mutable, tag-only, or receipt-less overrides fail closed. OpenClaw and PicoClaw retain their explicit local-image overrides. For `build`/`up` on a docker `--context`, Moltnet release assets are staged for that context's architecture (`amd64` or `arm64`); for local-only manual compile targeting a fixed architecture, set `SPAWNFILE_MOLTNET_TARGET_ARCH=amd64|arm64`. - -`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. For a remote Docker context where the local record is missing, pass `--context ` with `--live` to recover the deployment from Spawnfile container labels. - -`spawnfile dev` is the source-backed interactive loop. Hot apply remains runtime-specific. Public `runtime: daimon` v2 hosts support durable native cron/every/disabled schedules and authenticated Moltnet wake delivery; unsupported surfaces remain explicit in the capability report. - -Before automating Spawnfile, query the installed CLI rather than inferring -support from its package version: - -```bash -spawnfile capabilities --json +```text +Spawnfile + workspace ─→ compile ─→ runtime files ``` -This command only reads Spawnfile's packaged version and emits one strict -`spawnfile.capabilities.v1` JSON document. It does not read standard input, -write files, or contact Docker. The receipt identifies the target resolver, -closed composed-lifecycle command set, optional model-auth behavior, local -evidence helper, and typed terminal-artifact absence contracts. Capabilities -describe the installed CLI surface; target and auth preflight can still fail -for a particular machine or project. See -[`specs/TARGETS.md`](specs/TARGETS.md#capability-discovery). +## Try it -For a local Docker target, Spawnfile prepares and journals the package-owned -helper under its private target state: +Start with one agent. Requires **Node.js 22.19+**; compilation needs no Docker or model credentials. ```bash -# node:22-bookworm-slim must already be present in this Docker context. -spawnfile helper prepare-evidence-export \ - --context default \ - --json - -spawnfile target resolve_config \ - --context default \ - --evidence-destination "$PWD/.spawn-local/evidence.tar" \ - --prepare-evidence-helper +npm install -g spawnfile +spawnfile init my-agent +cd my-agent +spawnfile validate +spawnfile compile ``` -The helper command uses only the explicitly named local context, performs a -network-disabled build from package-shipped source, never pulls or pushes, and -keeps a fsynced pending transaction authority before its first Docker mutation. -The public result is only a versioned opaque handle and digest; reuse re-attests -the exact context, daemon, base config, platform, recipe, and image config -identity. No registry manifest or caller-managed authority file is required. +This creates an OpenClaw project with `IDENTITY.md`, `SOUL.md`, and `AGENTS.md`, then writes runtime configuration, a workspace, and container files into `.spawn/`. Read `spawnfile-report.json` there to see how your source was compiled. **The agent is configured, but has not started.** -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`](specs/DISTRIBUTION.md). +Edit the Markdown files to define who the agent is and what it should do, then compile again. Keep the source in Git; `.spawn/` is generated and ignored. -### Target adapter CLI +## From one agent to a team -`spawnfile target` is the explicit, non-interactive target-adapter boundary for -an external orchestrator. It takes one absolute request JSON file and one -strict private configuration object on standard input — never a configuration -path or inline configuration: +A team references individual agent projects. For example, once you have two projects with distinct agent names: -```bash -target-config-producer | spawnfile target --config - create_data_network /absolute/path/request.json +```yaml +spawnfile_version: "0.1" +kind: team +name: research-team +mode: swarm +members: + - id: researcher + ref: ./agents/researcher + - id: writer + ref: ./agents/writer ``` -On success it writes exactly one canonical JSON receipt followed by a newline. - -For a crash-safe machine caller handoff, project-mode `up --json`, `artifacts export ---json`, and `down --json` accept `--lifecycle-invocation lci_`. Spawnfile -binds that id to the exact operation, correlation, and request policy, atomically stores -the exact JSON bytes after the owner returns and before stdout, and rejects reuse with -drift. `spawnfile lifecycle lookup ` is read-only and returns one versioned state: -`not_applied`, `pending`, `completed`, or `ambiguous`, without Docker/provider -inspection. Recovery only resumes an operation when that command verifies exact durable -evidence that resumption is safe; otherwise it seals `ambiguous` and fails closed. -It writes no secret values to output or diagnostics. The full verb list, -request/receipt contract, and exit behavior are in [`specs/TARGETS.md`](specs/TARGETS.md). -`target lookup_operation` accepts the original mutation request with a minimal -read-only context config and reports `completed`, `pending`, or `not_applied` -without calling the target provider or changing its journal. - -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. +Each member has its own Spawnfile, identity, and runtime. Teams can share instructions and resources, contain nested teams, and declare [Moltnet](https://moltnet.dev) rooms. The [team guide](https://spawnfile.com/guides/teams/) covers the full setup; [examples](examples/) show complete projects. -## Project structure +## What travels with your team -A Spawnfile project is either an `agent` or a `team`. +- **Identity and instructions:** Markdown documents, skills, and workspace resources. +- **Tools and models:** MCP connections, model selection, and declared secret requirements. +- **Team structure:** Members, nested teams, shared resources, and schedules. +- **Communication:** Declared [Moltnet](https://moltnet.dev) networks and rooms for agents to exchange messages across runtimes. +- **Deployment:** Runtime configuration, container files, and a capability report built from the same source. -**Agent** - -```text -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 -``` +A team declaration alone does not create a conversation or a useful division of work. Give the agents a task, configure their communication, and choose how they wake. Start with the [team guide](https://spawnfile.com/guides/teams/) and [example projects](examples/). -**Team** +## Run and share it -```text -my-team/ -├── Spawnfile -├── TEAM.md -├── shared/skills/... -└── agents/ - ├── orchestrator/Spawnfile - ├── researcher/Spawnfile - └── writer/Spawnfile -``` +Once the prompts and configuration are ready: -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. +1. **Provide credentials.** Import an existing subscription login or configure provider credentials with [auth profiles](https://spawnfile.com/guides/docker/). Keep secret values out of Git. +2. **Build and start.** With Docker available, `spawnfile up . --detach --auth-profile ` compiles, builds, and starts the project. A Docker context can target another machine. +3. **Check the deployment.** `spawnfile status . --live` probes the running deployment; `spawnfile status .` reads only local declared and compiled state. +4. **Share an image.** `spawnfile publish` packages the project for an OCI registry so another operator can run it without the source, using their own credentials. -Not every file is required. Spawnfile names the portable roles; adapters decide how to lower them into runtime-native surfaces. See [`specs/SPEC.md`](specs/SPEC.md) for the full shape. +See [container deployment](specs/CONTAINERS.md), [status](specs/STATUS.md), and [image distribution](specs/DISTRIBUTION.md) for complete commands and requirements. ## Runtime support -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) | -| Daimon | active | | Subscription CLI engines, Moltnet | -| Pi | active | | Embedded org app, Moltnet client config | -| 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`](specs/RUNTIMES.md) for the live matrix and pinned versions, or [`runtimes.yaml`](runtimes.yaml) for the registry source of truth. - -## Why - -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. +| Runtime | Use it for | +|---|---| +| **Daimon** | Agents using harnessed engines, with Moltnet and memory integration. | +| **OpenClaw** | OpenClaw agents and their native messaging surfaces. The default agent scaffold. | +| **PicoClaw** | PicoClaw agents and their native messaging surfaces. | -## Docs +Daimon requires a pinned runtime image matching the compiler contract. The older `pi` adapter remains available for existing projects. -Hosted docs with rendered specs, runtime guides, and a capability matrix: **[spawnfile.com](https://spawnfile.com)** — start at [Introduction](https://spawnfile.com/introduction/), [Quickstart](https://spawnfile.com/quickstart/), or the [Runtimes overview](https://spawnfile.com/runtimes/overview/). +Portability is capability-specific: the compiler reports each feature as **supported**, **degraded**, or **unsupported**. Read that report before switching runtimes. Exact versions live in [runtimes.yaml](runtimes.yaml); the [runtime specification](specs/RUNTIMES.md) describes the adapter model. -The source-of-truth specs live in this repo: - -- [`specs/INDEX.md`](specs/INDEX.md) — map of all specs -- [`specs/SPEC.md`](specs/SPEC.md) — canonical source format -- [`specs/COMPILER.md`](specs/COMPILER.md) — compiler architecture and adapter contract -- [`specs/CONTAINERS.md`](specs/CONTAINERS.md) — container compilation -- [`specs/RUNTIMES.md`](specs/RUNTIMES.md) — runtime registry and version pinning -- [`specs/SURFACES.md`](specs/SURFACES.md) — messaging surface model -- [`specs/STATUS.md`](specs/STATUS.md) — static and live operational status -- [`specs/DISTRIBUTION.md`](specs/DISTRIBUTION.md) — image distribution, publish, and sourceless run -- [`specs/research/WORKSPACE-PACKAGING.md`](specs/research/WORKSPACE-PACKAGING.md) — planned source-directory and toolset authoring; not implemented -- [`fixtures/`](fixtures/) — test-only projects; [`examples/`](examples/) — user-facing examples -- [`scripts/README.md`](scripts/README.md) — maintained tooling and its callers -- [`archive/`](archive/) — historical plans, diagrams, and retired tooling - -## From source - -The normal source build requires only Node.js 22+ and uses the checked-in, -checksum-verified Linux x64 and arm64 helper artifacts. It does not invoke -Docker or access the network. - -```bash -git clone https://github.com/noopolis/spawnfile.git -cd spawnfile -nvm use -npm install -npm run build -npm link -``` - -Maintainers rebuilding those native artifacts must additionally have Docker -with BuildKit, the pinned `gcc:14.2.0` builder image available, and QEMU/binfmt -enabled for both `linux/amd64` and `linux/arm64`. Run `npm run build:native`, -then `npm run build`; CI performs the same rebuild and syscall verification on -pull requests, `main`, and package publication. - -For local development without linking globally: - -```bash -npm run dev -- validate test/fixtures/single-agent -``` +## Go further -## Contributing +| I want to… | Read | +|---|---| +| Understand the source format | [Spawnfile specification](specs/SPEC.md) | +| Explore complete projects | [Examples](examples/) | +| Add an adapter or contribute | [Contributing](CONTRIBUTING.md) | +| Integrate with deployment tooling | [Target and lifecycle contracts](specs/TARGETS.md) | +| Find a detailed contract | [Specification index](specs/INDEX.md) | -See [CONTRIBUTING.md](CONTRIBUTING.md) for local setup, tests, and the runtime adapter contract. +Spawnfile is part of [Noopolis](https://github.com/noopolis). [Moltnet](https://moltnet.dev) supplies messaging; [Daimon](https://github.com/noopolis/daimon) runs individual agents; [Simfile](https://simfile.org) builds simulation worlds around organizations. You can use Spawnfile on its own. ## License -MIT — see [LICENSE](LICENSE). +[MIT](LICENSE) --- -**[spawnfile.com](https://spawnfile.com)** · **[github.com/noopolis/spawnfile](https://github.com/noopolis/spawnfile)** +**[spawnfile.com](https://spawnfile.com)** · **[Examples](examples/)** · **[Contributing](CONTRIBUTING.md)** From 468176f72658e037c90a69054754bbd2b96beda3 Mon Sep 17 00:00:00 2001 From: Juan Cruz Fortunatti Date: Sat, 12 Sep 2026 14:18:05 +0200 Subject: [PATCH 2/2] docs: clarify team setup and runtime portability --- README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 58e45fd..11eccbd 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Spawnfile -> An agent team you can keep in Git. +> Write your agent team once. Compile it for different runtimes.

npm @@ -32,13 +32,13 @@ spawnfile validate spawnfile compile ``` -This creates an OpenClaw project with `IDENTITY.md`, `SOUL.md`, and `AGENTS.md`, then writes runtime configuration, a workspace, and container files into `.spawn/`. Read `spawnfile-report.json` there to see how your source was compiled. **The agent is configured, but has not started.** +`init` creates an OpenClaw project with `IDENTITY.md`, `SOUL.md`, and `AGENTS.md`. `compile` writes runtime configuration, the generated workspace, and container files into `.spawn/`. Read `spawnfile-report.json` there to see how your source was compiled. **The agent is configured, but has not started.** Edit the Markdown files to define who the agent is and what it should do, then compile again. Keep the source in Git; `.spawn/` is generated and ignored. ## From one agent to a team -A team references individual agent projects. For example, once you have two projects with distinct agent names: +A team has its own `Spawnfile`, which references the member agent projects. Create its directory with `spawnfile init my-team --team`. Once you have two projects with distinct agent names under `my-team/agents/`, put their references in `my-team/Spawnfile`: ```yaml spawnfile_version: "0.1" @@ -56,9 +56,9 @@ Each member has its own Spawnfile, identity, and runtime. Teams can share instru ## What travels with your team -- **Identity and instructions:** Markdown documents, skills, and workspace resources. +- **Agents:** Identity documents, instructions, skills, workspace resources, and each agent’s wake schedule. - **Tools and models:** MCP connections, model selection, and declared secret requirements. -- **Team structure:** Members, nested teams, shared resources, and schedules. +- **Team structure:** Members, nested teams, and shared resources. - **Communication:** Declared [Moltnet](https://moltnet.dev) networks and rooms for agents to exchange messages across runtimes. - **Deployment:** Runtime configuration, container files, and a capability report built from the same source. @@ -79,7 +79,7 @@ See [container deployment](specs/CONTAINERS.md), [status](specs/STATUS.md), and | Runtime | Use it for | |---|---| -| **Daimon** | Agents using harnessed engines, with Moltnet and memory integration. | +| **Daimon** | Agents using subscription CLI engines such as Codex and Claude Code, with Moltnet and memory integration. | | **OpenClaw** | OpenClaw agents and their native messaging surfaces. The default agent scaffold. | | **PicoClaw** | PicoClaw agents and their native messaging surfaces. |