agents are markdown
Browse docs

Start here

The format

Reference

Why it works this way

Docs/Reference

CLI reference

foldrun needs no account. ANTHROPIC_API_KEY (or CLAUDE_CODE_OAUTH_TOKEN) is enough to run agents; init and check need nothing at all.

Commands
foldrun init [dir] create a workspace that runs immediately
foldrun check [dir] validate agents, flows, tools, evals, knowledge — offline
foldrun run <target> run an agent or a flow (name, or flow:name)
foldrun eval [name] one eval, or all of them
foldrun probe <model> can this model hold a tool loop here? A live check
foldrun logs [run-id] recent runs, or one run’s whole event trail
foldrun secrets set NAME store a secret — also ls, rm
foldrun deploy [dir] push a workspace into an installation
foldrun invoke <flow> start a flow on a running platform — --watch follows its trace here
foldrun open [page] the dashboard for this workspace, in the browser (runs, agents, graph, repo…)

Options
--workspace <dir> the workspace folder (default .)
--from <template> start from a shipped template, e.g. templates/hello
--task "<text>" the instruction for a manual run
--follow logs: keep tailing a live run — locally, or on the platform with --url
--watch invoke: follow the run’s trace here as it happens; the exit code is the run’s
--print open: print the URL, do not open it
--value "<text>" secrets set: skip the prompt — careful with shell history
--account secrets: account scope rather than this workspace’s
--wait invoke: hold on and print the result
--from <n> invoke: start at step n, skipping earlier ones

Talking to a platform

deploy, invoke and secrets all reach a running installation:
--url <url> the platform, or FOLDRUN_URL
--token <key> an API key, or FOLDRUN_TOKEN
--to <workspace> which workspace there (deploy defaults to the folder name)
--tenant <name> account to deploy into (local installations only)
--data <dir> the installation’s data directory
--commit <sha> record which commit a deploy is
--dry-run check and report, change nothing
--force deploy even while runs are in flight

check, run, eval and probe are local — they read the workspace on disk and the runs beside it. logs is local too, until --url (or FOLDRUN_URL) names a platform: then it lists that workspace’s runs there, prints one run’s trail, and --follow tails a live one. open always needs a platform.

The loop, in order

foldrun check                      # after every edit. Free.
foldrun run publish --task "..."   # locally, against real models
foldrun eval                       # did the change break an agent?
foldrun deploy --url $FOLDRUN_URL  # checked again server-side before it lives
foldrun invoke publish --watch     # run it there, trace streamed here
foldrun logs --to publish-desk     # what ran there lately
foldrun open runs                  # the same, in the browser

A push to any branch other than main previews it: the platform deploys the branch’s tree to <workspace>-preview-<branch> and runs its evals there. Previews never fire on a schedule, read the source workspace’s secrets, and disappear when the branch does.