Configuration

awf has no settings file. A workflow says what a run does; the command line says where it runs (awf commands). What is left is a few environment variables, the logins each harness keeps, and one name in .env.

Environment variables

awf's own

Variable	Meaning	Default
AWF_HERDR_SESSION	The Herdr session a run's TUI agents open in. Lowercase letters, digits and -, up to 32, not starting with -. awf starts a session named awf or awf-… when it isn't running; any other name must be running already (Harnesses).	awf
AWF_COORDINATOR_DIR	Where live runs keep the socket that awf reply, awf send and events reach them through. An absolute path, outside the workflow's folder. Set it the same for the run and for the commands that answer it.	~/.awf/coordinator

Keys and tokens

Variable	Meaning	Default
OPENROUTER_API_KEY	The key for jev, the built-in decision model. Read from the environment, else from .env (below). The engine holds it; no agent's environment has it.	unset: asking jev fails, saying the key is not set
CLAUDE_CODE_OAUTH_TOKEN	The login of a claude agent in a sandbox, from claude setup-token. Passed into the sandbox, never on a command line.	unset: a sandboxed claude is refused
CURSOR_API_KEY	The login of a cursor agent in a sandbox, a key from Cursor's dashboard.	unset: a sandboxed cursor is refused

Agents outside a sandbox use your harness logins as they are (Install).

Refused

awf run refuses to start while any of these is set, since each would switch an agent to per-token billing (Harnesses):

Harness	Variables
claude	ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_BASE_URL
codex	OPENAI_API_KEY, OPENAI_BASE_URL, CODEX_API_KEY

awf: runtime: subscription runtime refused metered credential environment: ANTHROPIC_API_KEY; the run did not start, and nothing of it is kept

Unset them in the shell you run awf from.

Where harnesses keep their state

awf reads each harness's own folder to find its agents' sessions, which awf logs and the usage in out.json come from, to copy a login into a sandboxed agent's home, and to keep sandboxes off it. It follows the variable the harness itself follows:

Variable	Harness	Default
CLAUDE_CONFIG_DIR	claude; its account file is .claude.json in it, else ~/.claude.json	~/.claude
CODEX_HOME	codex	~/.codex
PI_CODING_AGENT_DIR	pi	~/.pi/agent
CURSOR_CONFIG_DIR	cursor	$XDG_CONFIG_HOME/cursor when XDG_CONFIG_HOME is set, else ~/.cursor

Others awf reads

Variable	Meaning	Default
XDG_CACHE_HOME	The skills cache is awf/skills under it (Data).	~/.cache
GIT_SSH_COMMAND	The ssh command git uses to fetch a skill from a repository.	ssh -o BatchMode=yes, so a fetch never stops to ask for a passphrase
HOME	Where ~/.awf and each harness's default folder are. A codex agent given skills is kept from the shared ones in $HOME/.agents/skills.	your home
DOCKER_HOST	The docker daemon the docker sandbox uses; a unix:// socket is kept out of every box, as is /var/run/docker.sock when it is unset.	docker's
NO_COLOR	Set to anything, awf's terminal output has no colour.	colour on a terminal
HERDR_HOME, XDG_*	Passed on to a Herdr server awf starts, where they move Herdr's own folder.	Herdr's

Set by Herdr

Herdr sets these in each of its panes, and awf run --here reads them to find the session it was typed in (Calling session): HERDR_ENV, HERDR_SOCKET_PATH, HERDR_PANE_ID, HERDR_WORKSPACE_ID and HERDR_TAB_ID. It also reads the session id the calling agent's harness sets, CLAUDE_CODE_SESSION_ID, CODEX_SESSION_ID, PI_SESSION_ID or CURSOR_CONVERSATION_ID, and passes it on to the run. You don't set any of them.

What an agent doesn't get

Outside a sandbox an agent gets your environment, less a few names: Security lists them. One of them is a setting: CLAUDE_CODE_EFFORT_LEVEL is removed so a claude agent runs at the effort its workflow set.

Files

File	Read for	Default
.env in the folder you run awf in	OPENROUTER_API_KEY only, when the environment doesn't set it	none
the workflow file	the workflow: awf run {file}	none
--values {file}	a JSON object of stage values, by stage name, to start part-way (Runs)	none
--sandbox {file}	a JSON sandbox spec every agent of the run works in (Sandboxes)	none
~/.awf/herdr/config.toml	the config of the Herdr sessions awf starts; awf writes it once and never overwrites it, so your edits stay	toasts and sound off

awf run and awf test don't load .env as Bun otherwise would: a token in it would change how every agent logs in (Security). One exception: a run with events that awf emit or awf tick starts in the background gets the PATH it was made with, a few plain variables, and the project's .env, not your shell's environment (Hosting events). AWF_COORDINATOR_DIR and AWF_HERDR_SESSION are among the variables it keeps, so set them where the sender runs.

Everything awf writes, and where, is on Data.