husk.yaml reference

husk.yaml is the whole agent in one file: portable, diffable, reviewable, and the only thing the runtime needs to bring a bot up. It is validated by a zod schema, so an invalid file fails with every problem listed at once rather than the first one.

husk init                    # scaffold one
husk validate                # check ./husk.yaml
husk validate support.yaml   # or a named file

The smallest valid file

name is the only required field. Everything else has a default.

name: my-bot

That expands to a husk on model: auto with an empty persona, the computer tool bundle, a cli trigger, and every limit at its default.

Top level

persona

The system prompt. {{var}} placeholders are interpolated from RunOptions.vars (husk run --var key=value); an unknown variable is left intact rather than blanked.

At run time Husk appends two sections when they have content:

• ## Reference — one ### <title> block per knowledge item.
• ## Out of scope — Decline these, briefly, and say what you can do instead: followed by one bullet per guardrails.refuse entry.

knowledge

knowledge:
  - title: Repository layout
    content: |
      packages/* are libraries, apps/* are deployables.
    source: https://github.com/org/repo   # optional, free-form

title and content are required; there is no length cap in the schema.

examples

examples:
  - user: main is red
    assistant: >
      The `build (node 20)` job failed at `packages/core` with TS2345.

Both sides required.

tools

Bundle names expand; individual names are also accepted.

A tool that cannot work is skipped rather than registered-and-broken: a tool the model can see is a promise that calling it will do something. Tools needing a machine are dropped when computer.enabled is false, and http_request is opt-in — naming the http bundle counts as naming it.

computer

computer:
  enabled: true
  flavor: python
  packages: [pandas, numpy]
  network:
    mode: egress
    allow: ['pypi.org', 'files.pythonhosted.org']
  memoryMb: 4096
  idleTimeoutSec: 600
  persist: true
  setup: mkdir -p /work/out

computer.labels

Per-husk provider configuration, for the two providers that point at something outside this machine. Set here, a husk.yaml needs no environment variables at all:

computer:
  provider: ssh
  labels:
    husk.ssh: deploy@build-box:2222
    husk.ssh.key: ~/.ssh/id_ed25519

The label wins over the environment, so one machine can drive several boxes. Values are strings; anything else is rejected at parse time. Husk adds a husk.key label of its own when it binds a machine to a session — do not set that one.

computer.network

An egress policy with no allow list permits nothing.

computer.mounts

mounts:
  - source: ./data
    target: /work/data
    readonly: true

source and target are required. readonly defaults to true — a host mount is the one hole in a container, and an agent that only needs to read a repository must not rewrite it.

computer.env

Explicit values always win over the environment scrub, which is how you pass a credential deliberately:

computer:
  env:
    GITHUB_TOKEN: ${GITHUB_TOKEN}

Explicit beats implicit, and now it is in the file where a reviewer can see it.

limits

limits:
  maxSteps: 20
  maxCostUsd: 0.25
  timeoutSec: 240

Every ceiling is checked before the next model call, not after, so a run stops rather than overshooting. See Cost and budgets for what the cost estimate can and cannot know.

guardrails

guardrails:
  approvalMode: auto
  denyCommands:
    - 'git\s+(push|commit|reset\s+--hard)'
  refuse:
    - deploying, reverting, or merging anything

allowCommands wins over denyCommands and over the built-in deny list: an explicit allow entry is you saying you know better about your own machine, and you do. An entry that is not valid regex falls back to a substring match rather than throwing.

approvalMode

ask fails closed. A headless server running an ask-mode husk denies rather than allows, which is the only safe default for a mode whose whole point is a human in the loop.

Dangerous tools: shell, write_file, edit_file, move, delete, expose_port, http_request. Not dangerous: read_file, list_dir, search_files, computer_info, fetch_url, web_search.

memory

memory:
  enabled: true
  windowTurns: 20
  summarise: true

With enabled: true, the loop keeps the system messages, the first user message as an anchor, and the last windowTurns turns. The middle is either replaced by a model-written summary or by a marker:

[husk: 42 earlier messages summarised]
…
[husk: 42 earlier messages elided to stay inside the context window]

Cuts land on turn boundaries and orphaned pairs are pruned, so a tool_call is never separated from its tool_result. The summary call is charged to the run's budget.

triggers

triggers:
  - type: http
  - type: cron
    schedule: '*/15 * * * *'
    prompt: Any red builds on main in the last 15 minutes?

The schema accepts seven types. Three are wired into the server — see Triggers for which and what happens to the rest.

metadata and origin

metadata is a free-form record carried through untouched. Husk itself writes exactly two keys into it, both from distillation:

These names are the contract. Every path that distils — husk distill, POST /v1/sessions/distill, and toSpec in @husk-ai/sessions directly — goes through the one mapper and writes these two. Nothing writes distillConfidence or distillNotes; if you are reading a husk.yaml written by an older build, those are the same two values under the old spellings.

Everything else under metadata is yours, and husk will not touch it.

origin records provenance. It survives a round trip through husk validate and back out to YAML, so a distilled husk can always say where it came from:

A complete example

apiVersion: husk/v1
name: ci-triage
displayName: CI Triage
version: 0.2.0
description: Reads failing CI logs and says what broke, in one paragraph.
 
model: sonnet
fallbackModels: [flash, gemma]
 
persona: |
  You triage CI failures for a TypeScript monorepo.
 
  Always read the failing job's log before forming an opinion. Quote the first
  line that actually failed -- not the last line, which is usually the runner
  giving up.
 
  Answer in one paragraph. No preamble.
 
knowledge:
  - title: Repository layout
    content: |
      packages/* are libraries, apps/* are deployables. Any change under
      packages/core forces a full rebuild.
 
tools: [computer, files]
 
computer:
  flavor: node
  network:
    mode: egress
    allow: ['*.github.com', 'objects.githubusercontent.com']
  idleTimeoutSec: 600
 
limits:
  maxSteps: 20
  maxCostUsd: 0.25
  timeoutSec: 240
 
guardrails:
  approvalMode: auto
  denyCommands:
    - 'git\s+(push|commit|reset\s+--hard)'
    - 'gh\s+(pr|release)\s+(create|merge|edit)'
  refuse:
    - deploying, reverting, or merging anything
 
triggers:
  - type: http
  - type: cron
    schedule: '*/15 * * * *'
    prompt: Any red builds on main in the last 15 minutes? If none, reply exactly "clear".

Validation errors

Every problem at once, each as path: message:

error husk.yaml is not a valid husk
  ✗ name: name must be lowercase alphanumeric with dashes
  ✗ limits.maxSteps: Number must be less than or equal to 500
  ✗ triggers.0.schedule: Required
hint:  `husk init --force` regenerates a valid file, or see `husk help init`

The same check is available over the control plane at POST /v1/husks/validate, which returns { ok, issues } with HTTP 200 either way — it is a validator, not an operation that can fail.