Agentfile

An Agentfile is a local, plain-text recipe for a repeatable worker: model, task, resource limits, tools, and optional isolation policy. ostk parses and validates supported launch paths; signing and supervision depend on the selected workflow rather than happening universally.

Agentfiles live at .ostk/agents/<name>.Agentfile (per-project workers) or .ostk/profiles/<name>.Agentfile (reusable templates). The lifecycle verbs are ostk agentfile new / list / show / lint / validate. Run with ostk run <path>. Source: src/commands/agentfile_cmd.rs, src/commands/run.rs.

PROBLEM_01 // WRITE_YOUR_FIRST

I want to spawn a worker for one task. Where do I start?

ostk agentfile new fix-bug-27 scaffolds a starter Agentfile from a profile template. Edit two things: the FROM directive (which model — anthropic, openrouter, ollama/, mlx/) and the TASK directive (the prompt that defines the work). Optional: tighten LIMIT budget_usd and LIMIT turns. Then ostk run spawns the worker.

TERMINAL

$ ostk agentfile new fix-bug-27
created: .ostk/agents/fix-bug-27.Agentfile

$ cat .ostk/agents/fix-bug-27.Agentfile
FROM claude-sonnet-4-6
LIMIT budget_usd 2
LIMIT turns 30
LIMIT wall_clock 600
TASK Fix the bug described in needle →27.
     Write a regression test, run cargo check, commit when green.

$ ostk run .ostk/agents/fix-bug-27.Agentfile

COMPOSES_FROM

agentfile new (scaffolder) · the FROM/LIMIT/TASK directives (the spec) · run (spawns the supported agent loop) · pin caps from OSTK_PIN or tier defaults · best-effort drain snapshots after completed managed turns.

Source: src/commands/agentfile_cmd.rs (new subcommand), src/commands/run.rs.

PROBLEM_02 // DECLARE_THE_FULL_SPEC

What can I actually declare? Beyond model + task.

Six directive families compose. Each one corresponds to a substrate concept the kernel will enforce — they're not hints, they're contracts. Most workers need only FROM + LIMIT + TASK; the rest are for fleet workers, supervisor trees, and reusable profiles.

FROM required Which model. anthropic prefixes (claude-sonnet-4-6), openrouter prefixes, ollama/, mlx/, or a profile reference (FROM-PROFILE base-coder).

LIMIT optional Resource bounds. budget_usd (rejected at parse time if 0/unlimited/negative), turns (agent-loop iterations), wall_clock (seconds), tokens (cumulative).

TASK required The prompt that defines the work. Multi-line via continuation. The agent loop sees this as its initial user message.

PIN optional Active pin profile name. Equivalent to setting OSTK_PIN=<name> at spawn. Resolves to .ostk/pins/<name>/pin.caps.

RESTART optional Supervisor restart strategy: one_for_one, one_for_all, rest_for_one, simple_one_for_one. Used by the application/v1 supervisor when this agent is part of a tree.

HEALTHCHECK optional Liveness probe. Cross-validates with RESTART and LIFETIME. The lint pass catches incompatible combinations.

COMPOSES_FROM

Directive parser · per-directive validators (e.g. parse_budget_usd rejects 0/unlimited/negative) · cross-directive linter (RESTART/LIFETIME/HEALTHCHECK consistency) · the kernel's runtime contract for each declared field.

Source: src/commands/agentfile_cmd.rs (lifecycle), src/serve/attenuation.rs (LIMIT parsing), src/cpu/agent_loop.rs (runtime enforcement).

PROBLEM_03 // SHARE_ACROSS_PROJECTS

I keep retyping the same scaffolding. How do I share it?

Profiles. .ostk/profiles/<name>.Agentfile is a reusable template. Any per-project Agentfile can FROM-PROFILE base-coder to inherit its directives. The receiving Agentfile can override or extend; conflicts go to the layered-spec resolver. Profiles can be machine-wide (under ~/.local/share/ostk/profiles/) for cross-project reuse, or shipped as part of a signed bail.

TERMINAL

# Create a reusable profile
$ cat .ostk/profiles/base-coder.Agentfile
FROM claude-sonnet-4-6
LIMIT budget_usd 5
LIMIT turns 50
PIN default

# Inherit from it in a per-task worker
$ cat .ostk/agents/fix-bug-27.Agentfile
FROM-PROFILE base-coder
LIMIT budget_usd 2          # override: tighter for this one
TASK Fix bug →27 ...

COMPOSES_FROM

Profile directory layout · FROM-PROFILE directive · layered-spec resolver (per-task overrides profile; profile overrides built-in defaults) · profile signing for cross-machine portability.

Source: src/commands/agentfile_cmd.rs (FROM-PROFILE resolution), src/commands/migrate.rs (legacy FROM-PROFILE migration, →1422).

PROBLEM_04 // VERIFY_BEFORE_RUN

I want to know my Agentfile is valid before I burn an LLM call on it.

Three layers of pre-flight. ostk agentfile show renders the parsed result with the signature status — fast sanity check. ostk agentfile lint runs cross-directive rules: RESTART without LIFETIME, HEALTHCHECK against an unreachable verb, FROM-PROFILE that points at a non-existent profile, LIMIT keys with malformed values. ostk agentfile validate is the full pre-flight: parse + sign-verify + lint, returns an OAE.4-style outcome envelope you can pipe into a CI gate.

TERMINAL

$ ostk agentfile show .ostk/agents/fix-bug-27.Agentfile
parsed: 5 directives, 0 unknown
signature: not signed (T2 author)
profile chain: base-coder → built-in defaults

$ ostk agentfile lint .ostk/agents/fix-bug-27.Agentfile
ok: 5 directives, 0 lint failures

$ ostk agentfile validate .ostk/agents/fix-bug-27.Agentfile
{"verdict":"pass","parse":"ok","sign":"unsigned-ok","lint":"ok"}

COMPOSES_FROM

Parser (directive grammar) · signer (Ed25519 in-process) · cross-directive linter · OAE.4 outcome envelope for machine-readable verdicts. Same machinery ostk run --dry-run uses.

Source: src/commands/agentfile_cmd.rs (show / lint / validate subcommands), src/util/oae.rs (outcome envelope format).

THE_COMPOSITION

A Dockerfile for agents.

Plain-text directives, ordered, parsed, signed, supervised. The Dockerfile analogy holds at every layer. FROM picks your base. LIMIT is your resource cap. FROM-PROFILE is your FROM <image> for templating. The lint pass is your build-time validation. The kernel signing is your image-digest equivalent. ostk run is your docker run.

Where the analogy diverges: Agentfiles aren't built into immutable artifacts at author time. They're parsed and signed at spawn time — the kernel reads the file, hashes its content, signs the hash with the operator's identity key, records the signed hash in the journal. Two spawns of the same Agentfile produce two distinct claim-graph entries with the same content hash. The audit chain is what makes the agent's runtime existence verifiable; the file is just the seed.

application/v1 generalizes Agentfiles into supervisor trees — multi-worker setups with restart strategies and shared budgets. Spec ratified at docs/spec/llmos-application.md; the application/v1 lifecycle verbs (ostk app *) land in a future release.