Install

awf runs on Bun, on macOS or Linux; on Linux it needs ps, from procps, which slim container images leave out. You install one package, agentswf, which puts the awf command on your PATH and gives a workflow its imports.

bun add -g agentswf   # puts awf in ~/.bun/bin
awf --version

~/.bun/bin is on your PATH if Bun's installer set it up. A plain install gets the newest release.

What you need

• Bun 1.4 or later.
• git.
• At least one coding agent CLI, logged in: claude, codex, pi or cursor. awf drives the CLI you already use, on your own login; it has no account of its own.
• Herdr, for TUI agents. A TUI agent runs its harness's own interface in a terminal pane you can watch and type into, and that is the default. A headless agent runs as a plain process and needs no Herdr. awf is built for Herdr 0.9.1, and requires exactly that version for a docker sandbox's own Herdr.

A workflow can live in any folder and needs nothing installed there: awf serves it agentswf/workflow, agentswf/typebox and typebox from its own copies, and awf test serves agentswf/client and agentswf/testing too. A folder that declares agentswf runs on the one it installs.

Each harness

A harness is the coding agent CLI an agent runs on. awf checks a harness's login when a run opens its first agent on it, so a run that uses only codex needs no claude login.

Harness	Command on PATH	Login it needs	Headless	In a sandbox, besides the login
claude	claude	a Claude subscription: claude, then /login	only with metered: true	CLAUDE_CODE_OAUTH_TOKEN, from claude setup-token
codex	codex	a ChatGPT login: codex login	yes	nothing
pi	pi	one per model provider: pi, then /login	yes	nothing
cursor	cursor-agent	cursor-agent login	yes	CURSOR_API_KEY, from Cursor's dashboard

A claude TUI agent runs on your plan, and headless claude is refused unless its runtime says metered: true; Harnesses says why, and what awf refuses in your environment.

claude and codex must be on a subscription login, not an API key; otherwise the agent doesn't open:

Codex subscription authentication is required (ChatGPT login); `codex login status` reads as …

pi's login is per provider, so awf doesn't check it up front. A login a turn finds missing or refused, pi's or one that lapsed mid-run, fails that turn at once, and its reason names the command to run:

pi needs a login for openai-codex: run `pi`, then /login (pi said: No API key found for openai-codex.)

claude and cursor keep their logins in the macOS keychain, which a sandbox can't reach, so a sandboxed agent of theirs reads a token from awf's environment instead.

Sandboxes

A sandbox limits what an agent can write and reach. It needs one of:

• srt, Anthropic's sandbox-runtime, with srt and node on your PATH. macOS only for now: on Linux awf refuses it, so use docker there. On its first use in a run awf checks that srt really confines on this machine, and stops if it doesn't.
• docker, with its daemon running and awf's image built once: the first docker sandbox stops with the docker build command to run (Troubleshooting). A docker sandbox runs its own Herdr, so its panes show in the run's workspace.

A run that opens no sandbox needs neither. Each sandbox names the one it uses: Sandboxes.

Editor types

awf init sets a folder up for writing workflows, with agentswf and typebox as dev dependencies so your editor has types; Quick start walks through it. Once installed there, that agentswf is the folder's engine, as the next section says.

Updating

A folder with no agentswf of its own runs on the global awf. Run the install again to update it:

bun add -g agentswf

A folder awf init set up has its own agentswf, and that is what runs its workflows: the global awf, run in that folder at another version, warns and hands the command over to it. Update it in the folder, then run the check and test scripts awf init wrote:

bun add -d agentswf
bun run check   # tsc --noEmit
bun run test    # awf test

Until bun install has run, a folder that declares agentswf without installing it is refused, naming bun install.

A release can improve the API. If it changed something your workflow uses, these show where, before any agent runs; hand the errors and the current llms.txt to your coding agent, and it moves the workflow over.

Catches

• A workflow file is trusted code: it runs with your permissions, so sandbox the agents, not the workflow (Security).
• Each harness is its own install. awf doesn't install or update claude, codex, pi, cursor or Herdr; keep each logged in with its own command.
• Work on agents.wf itself runs from a clone instead; the README says how.

Next

• Quick start: a first workflow, its free test, and one real run.
• Harnesses: models, effort, and which logins a run uses.
• Troubleshooting: what a refused login or a missing Herdr prints.
• Configuration: every environment variable awf reads or refuses.