husk.yaml schema index

name: my-bot

# The schema version. Bumped only on a breaking change.
apiVersion: husk/v1
 
# Required. Lowercase alphanumerics and dashes, 1-64 chars. This is the URL
# segment, the CLI handle, and the computer's name.
name: ci-triage
displayName: CI Triage        # <= 96 chars, human label
version: 0.2.0                # yours, not husk's
description: Reads failing CI logs and says what broke, in one paragraph.
 
# An alias or a provider/model id. `auto`, `free` and `local` are strategies.
model: sonnet
# Only honoured on the control-plane path; `husk run` pins one model.
fallbackModels: [flash, gemma]
temperature: 0.2              # omit to use the provider's default
 
# The system prompt. {{name}} placeholders come from `husk run --var name=…`.
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.
 
# Appended to the prompt under "## Reference".
knowledge:
  - title: Repository layout
    content: |
      packages/* are libraries, apps/* are deployables. Any change under
      packages/core forces a full rebuild.
    source: https://github.com/org/repo/blob/main/README.md
 
# Few-shot pairs. Both sides required.
examples:
  - user: main is red
    assistant: The `build (node 20)` job failed at `packages/core` with TS2345.
 
# Bundles, individual tool names, or both.
tools: [computer, files]
 
computer:
  enabled: true               # false removes the machine and every tool needing one
  flavor: node                # base | python | node | full
  # image: ghcr.io/me/custom:1   # overrides flavor
  cpus: 2
  memoryMb: 2048
  diskMb: 2048
  idleTimeoutSec: 600         # destroy after 10 min with no exec; 0 disables
  maxLifetimeSec: 0           # hard ceiling regardless of activity; 0 disables
  workdir: /work
  persist: false              # true keeps the filesystem across restarts
  packages: [pnpm]            # installed on first boot by the flavor's manager
  setup: mkdir -p /work/out   # one shell snippet, once, after creation
  env:
    GITHUB_TOKEN: ${GITHUB_TOKEN}   # explicit values survive the env scrub
  mounts:
    - source: ./fixtures
      target: /work/fixtures
      readonly: true          # the default; set false deliberately or not at all
  network:
    mode: egress              # none | egress | full
    allow: ['*.github.com', 'objects.githubusercontent.com']
    deny: ['telemetry.example.com']   # refused even in `full`
 
limits:
  maxSteps: 20                # 1-500
  maxCostUsd: 0.25            # 0 means "local models only"
  maxTokens: 200000
  timeoutSec: 240             # wall clock for the whole run
  execTimeoutSec: 120         # per exec inside the machine
  maxOutputBytes: 262144      # per tool result, before redaction
 
guardrails:
  approvalMode: auto          # auto | ask | readonly; `ask` fails closed
  denyCommands:
    - 'git\s+(push|commit|reset\s+--hard)'
  allowCommands: []           # beats denyCommands AND the built-in list
  refuse:
    - deploying, reverting, or merging anything
  redactSecrets: true
 
memory:
  enabled: false              # the only gate; off means history is never trimmed
  windowTurns: 20
  summarise: true
 
triggers:
  - type: http                # ALL /v1/t/ci-triage
  - type: cron
    schedule: '*/15 * * * *'
    prompt: Any red builds on main in the last 15 minutes? If none, reply "clear".
 
# Free-form, carried through untouched.
metadata:
  owner: platform-team
 
# Written by `husk distill`. `source` is required once the block exists.
origin:
  source: claude-code
  transcriptId: tr_01hxyz
  importedAt: 2026-09-01T10:00:00.000Z
  messageCount: 214

husk validate                 # ./husk.yaml
husk validate support.yaml
husk validate --json

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`