pod.toml reference

Every table and field in the pod.toml v0.1 manifest. konareef pod validate checks a pod against this schema offline; reef-core remains the authoritative parser and execution environment.

Minimal example

pod_spec_version = "0.1"

[pod]
name    = "hello-world"
version = "0.1.0"

[runtime]
kind = "lobster"

[directive]
task = "Say hello to the world and write it to ./greeting.md."

Top-level fields

[pod]

Pod identity. name and version are required.

[pod]
name        = "invoice-summarizer"
version     = "1.2.0"
description = "Summarizes invoices and extracts payment terms."
authors     = ["Dave <[email protected]>"]
license     = "MIT"
homepage    = "https://example.com/invoice-summarizer"
tags        = ["finance", "documents"]
lineage_id  = "37c90baadd4c3c8e79f544ed7356c17b"

[runtime]

The registered runtime that executes the pod. Required.

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

[model]

The model the runtime should use. The provider key is resolved from the reef-core vault at spawn — never stored here.

[model]
provider    = "anthropic"
name        = "claude-sonnet-4-5"
max_tokens  = 2000
temperature = 0.2

[hardware]

Optional resource requirements for the runtime.

[hardware]
cpu_cores = 4
memory    = "8GiB"
disk      = "20GiB"

[hardware.gpu]
kind     = "nvidia"
count    = 1
vram_gib = 24
model    = "A10G"

[dependencies]

External requirements. Secrets are declared by name only — values come from the reef-core vault at spawn.

[dependencies]
system  = ["pandoc"]
runtime = ["some-runtime-plugin"]
secrets = ["OPENAI_API_KEY", "GITHUB_TOKEN"]

[context]

Memory, skills, tools, and prompt files the pod composes at spawn.

[[context.prompts]]
role = "system"
path = "./prompts/system.md"

[[context.tools]]
source = "./tools/search.toml"

[[context.memory]]
kind     = "openbrain"
snapshot = "2026-06-01"

[inputs]

A map of input name → descriptor. Names match the identifier pattern. Inputs are surfaced to the directive template (e.g. {{name}}).

[inputs]
customer_name = { type = "string", required = true }
urgency       = { type = "enum", values = ["low", "normal", "high"], default = "normal" }
retries       = { type = "int", min = 0, max = 5, default = 1 }

Every input also accepts required (boolean) and description (string).

[directive]

What the pod should do. Provide exactly one of task (inline) or template (a Mustache file). Required.

[directive]
template       = "./prompts/system.md"
max_iterations = 5
tools_allowed  = ["web_search"]
tools_denied   = ["shell"]

[output]

The definition of done — success/failure predicates plus declared deliverables. This is not a JSON output schema.

[output]
format = "markdown"

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

[[output.success]]
kind  = "min_words"
path  = "./report.md"
count = 200

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

[[output.deliverables]]
path        = "./report.md"
description = "The finished report."

Predicate kinds (used in both success and failure):

Deliverables: path (required), description, optional (boolean).

[budget]

Hard spending caps, denominated in satoshis.

[budget]
max_sats          = 1000
per_call_cap_sats = 200
daily_cap_sats    = 5000

[wallet]

How the pod's spend wallet is provisioned.

[wallet]
strategy = "fresh"

[hooks]

Lifecycle scripts (repo-relative paths) run around spawn.

[hooks]
pre_spawn  = "./hooks/pre.sh"
on_success = "./hooks/done.sh"

Fields: pre_spawn, post_spawn, on_success, on_failure — each a ./… path.

[marketplace]

Listing metadata for pods published to the marketplace.

[marketplace]
listed      = true
price_model = "per_run"
price_sats  = 500
categories  = ["finance", "documents"]

Full example

pod_spec_version = "0.1"

[pod]
name        = "invoice-summarizer"
version     = "1.2.0"
description = "Summarizes invoices and extracts payment terms."
authors     = ["Dave"]
license     = "MIT"
tags        = ["finance", "documents"]

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

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

[dependencies]
secrets = ["OPENAI_API_KEY"]

[inputs]
customer_name = { type = "string", required = true }
urgency       = { type = "enum", values = ["low", "normal", "high"], default = "normal" }

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

[output]
format = "markdown"

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

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

[[output.deliverables]]
path        = "./summary.md"
description = "The invoice summary."

[budget]
max_sats          = 5000
per_call_cap_sats = 500

[wallet]
strategy = "fresh"

[marketplace]
listed      = true
price_model = "per_run"
price_sats  = 500
categories  = ["finance"]

Common mistakes

• Missing a required table — pod_spec_version, [pod], [runtime], and [directive] must all be present.
• Both task and template in [directive] — provide exactly one.
• A file path without the leading ./ — v0.1 only accepts repo-relative paths.
• An unknown field or misspelled table — extra keys are rejected; run konareef pod validate to catch them.
• Putting a secret value in [dependencies].secrets — declare the name only.
• Expecting dollars — budgets are in satoshis.