Build your first reefpod

In about fifteen minutes you will scaffold a reefpod, validate it against the pod.toml v0.1 schema, and shape it into a pod that greets a person by name. Everything here runs locally — no account, no network.

What you will build

hello-world — a tiny reefpod whose directive greets a supplied name and writes the greeting to a file. You will declare its runtime, model, input, budget, and definition of “done,” then confirm the whole thing is valid.

What you will learn

• How konareef pod init scaffolds a valid pod.
• How to validate a pod offline with konareef pod validate.
• The core pod.toml tables: [pod], [runtime], [model], [inputs], [directive], [output], [budget].
• That “output” is a definition of done, not a JSON schema.

Prerequisites

• konareef installed and on your PATH — see Install konareef.

Final project structure

hello-world/
  pod.toml
  prompts/
    system.md

Step 1 — Scaffold the pod

konareef pod init hello-world

This creates a starter directory and prints:

created pod "hello-world" (3 files)
   hello-world/pod.toml
   hello-world/prompts/system.md
   hello-world/README.md

Next: konareef pod validate hello-world/pod.toml

Pod names must start with a lowercase letter and contain only lowercase letters, digits, -, or _.

Step 2 — Validate it (your first success)

konareef pod validate ./hello-world/pod.toml

Expected output:

./hello-world/pod.toml: valid

That is your first success moment: a schema-valid reefpod, verified offline against the vendored v0.1 schema. Everything from here is shaping.

Step 3 — Read the scaffold

Open hello-world/pod.toml. The scaffold looks like this:

pod_spec_version = "0.1"

[pod]
name        = "hello-world"
version     = "0.1.0"
description = "TODO: describe what hello-world does."
lineage_id  = "…"                 # generated per pod

[runtime]
kind    = "lobster"               # one-shot runtime shipping in reef-core
version = "^0.1"

[model]
provider = "anthropic"
name     = "claude-sonnet-4-5"

# [inputs]                        # commented out by the scaffold
# topic = { type = "string", required = true, description = "What to work on." }

[directive]
template       = "./prompts/system.md"
max_iterations = 5

[output]

[[output.failure]]
kind  = "timeout_seconds"
value = 600

[[output.failure]]
kind = "budget_exhausted"

[budget]
max_sats = 1000

Step 4 — Make it greet by name

Now shape the pod. First, rewrite the directive template hello-world/prompts/system.md to greet the input and produce a deliverable file:

You are a friendly KonaReef pod.
Greet {{name}} in one warm sentence and write it to ./greeting.md.

Then edit pod.toml: add an [inputs] block, and make [output] declare what success looks like — a greeting.md file. Here is the complete result:

pod_spec_version = "0.1"

[pod]
name        = "hello-world"
version     = "0.1.0"
description = "A tiny reefpod that greets a user by name."

[runtime]
kind    = "lobster"
version = "^0.1"

[model]
provider = "anthropic"
name     = "claude-sonnet-4-5"

[inputs]
name = { type = "string", required = true, description = "The name to greet" }

[directive]
template       = "./prompts/system.md"
max_iterations = 3

[output]

[[output.success]]
kind = "file_exists"
path = "./greeting.md"

[[output.failure]]
kind  = "timeout_seconds"
value = 120

[[output.failure]]
kind = "budget_exhausted"

[[output.deliverables]]
path        = "./greeting.md"
description = "The generated greeting."

[budget]
max_sats = 1000

Step 5 — Validate again

konareef pod validate ./hello-world/pod.toml

./hello-world/pod.toml: valid

What happened

• [pod] — identity: name, semver, description (and a generated lineage_id).
• [runtime] — which reef-core runtime executes the pod. Required.
• [model] — the provider + model the runtime should use; the key is resolved from the reef-core vault at spawn, not stored here.
• [inputs] — name is a required string, surfaced to the directive as {{name}}.
• [directive] — the prompt template plus an iteration cap. Required (inline task or a template path).
• [output] — the definition of done: succeed if greeting.md exists; fail on timeout or budget exhaustion; the file is a declared deliverable.
• [budget] — a hard cap of 1000 satoshis for the run.

Running it

Reefpods execute on a reef-core deployment, which produces a signed custody proof of the run. The one-command public konareef pod spawn ./pod.toml flow is landing soon. Until then, the way to exercise a pod end-to-end is to create a publisher identity, publish it, then install, verify, and smoke-test it against a reef-core deployment.

Common mistakes

• Pod name starting with a digit, uppercase, or symbol — it must match ^[a-z][a-z0-9_-]*$.
• Providing both task and template in [directive] — choose exactly one.
• Expecting a budget in dollars — budgets are in satoshis (max_sats).