Environment variables and files

This page lists every environment variable that instruction, instruction agents and instruction-mcp read, and every file they write on your machine and in a project. Use it to run the tools in CI, in a container, or with a non-default config folder.

Environment variables

The table is generated from the three packages' source when this site is built. It lists every variable the code reads whose name starts with INSTRUCTION_MD_, plus the general variables the tools take into account. "Code of" names the package whose code reads it: instruction (the instruction.md package), instruction agents (@instruction.md/agents) or instruction-mcp (@instruction.md/mcp). instruction agents is built on the instruction.md package, so it also honours what instruction reads: its hooks, runner and sign-in use the same connection code.

A flag always wins over its variable: --url over INSTRUCTION_MD_URL, --token over INSTRUCTION_MD_TOKEN, --issuer over INSTRUCTION_MD_ISSUER, and so on.

VariableCode ofWhat it doesDefaultExample
INSTRUCTION_MD_URLinstruction, instruction agents, instruction-mcpThe instruction.md MCP server. Registry commands and instruction login take it after --url. The hooks, turn, acp and the instruction.md/agent helper take it after --url and the follow file's url. instruction-mcp --http sends every request there.Registry commands: the server of your last instruction login, else https://instruction.md/mcp. instruction login, the hooks and instruction-mcp --http: https://instruction.md/mcphttps://instruction.md/mcp
INSTRUCTION_MD_TOKENinstruction, instruction agentsA bearer token, used as it is instead of the stored sign-in: never refreshed, and never replaced by a new sign-in. The same as --token. In CI, an agent credential's access token.The sign-in stored by instruction login$TOKEN (minted from an agent credential)
INSTRUCTION_MD_ISSUERinstruction, instruction-mcpinstruction login: the authorization server to sign in at, the same as --issuer. One that isn't the server's own asks first, or needs --trust-issuer. instruction-mcp --http: the issuer its protected-resource metadata names, the same as --issuer.instruction login: the one the server names. instruction-mcp: /auth/realms/instruction-md at the server's originhttps://instruction.md/auth/realms/instruction-md
INSTRUCTION_MD_CLIENT_NAMEinstruction, instruction agents, instruction-mcpThe client name every request sends in its client information. The server counts reads by app with it. Each command sets its own when it is unset.instruction-md-cli; a hook: instruction-md-cli hook (<app>); instruction agents turn: instruction-md-cli <app>; the runner: instruction-md-cli fleet@<hostname>; instruction-mcp: instruction-mcp, or instruction-mcp (company proxy)acme-release-pipeline
INSTRUCTION_MD_LABELinstructionThe client title every request sends: how this machine is named among an instruction's consumers.cli@<HOSTNAME> (local when HOSTNAME is unset); instruction mcp and instruction-mcp: instruction mcp@<host name>ci@github-actions
INSTRUCTION_MD_CACHEinstructionWhere an instruction followed by its address, not by a project, keeps its current.md and state.json: one folder per address under follow/. Managed hooks, --follow and INSTRUCTION_MD_FOLLOW use it.$XDG_CACHE_HOME/instruction-md, else ~/.cache/instruction-md/var/cache/instruction-md
INSTRUCTION_MD_ACCOUNTSinstruction agentsThe accounts file: what each MCP server's account means on this machine (instruction agents accounts, credential, check, apply). The runner passes its own to each agent it starts.$XDG_CONFIG_HOME/instruction-md/accounts.json, else ~/.config/instruction-md/accounts.json/etc/instruction-md/accounts.json
INSTRUCTION_MD_MCP_TOKENSinstruction agentsThe file of sign-ins to other MCP servers, written by instruction agents signin and read by instruction agents credential.$XDG_CONFIG_HOME/instruction-md/mcp-tokens.json, else ~/.config/instruction-md/mcp-tokens.json/run/secrets/mcp-tokens.json
INSTRUCTION_MD_FOLLOWinstruction agentsThe instruction to follow in a folder that has no .instruction/follow.json: instruction agents turn, acp and the pi extension read it. The runner sets it, with INSTRUCTION_MD_DEPLOYMENT, for every agent it starts.None: only the project's follow fileinstruction://acme/support-agent@stable
INSTRUCTION_MD_REQUIRE_SIGNATUREinstruction agents1: an instruction followed through INSTRUCTION_MD_FOLLOW takes signed versions only.Unset: as the follow says1
INSTRUCTION_MD_SEAL_KEY_FILEinstruction, instruction-mcpA key file (imd-seal/1, as instruction-mcp key init writes it) that opens sealed instructions. instruction-mcp: the same as --key-file. instruction and instruction agents: what opens a sealed instruction they follow or a sealed conversation.None/keys/agent.key
INSTRUCTION_MD_SEAL_KEY_COMMANDinstruction, instruction-mcpA command that prints the key file's JSON, for a key kept in a KMS or secret store. It runs once, through the shell, with 30 seconds to answer, and wins over a key file. instruction-mcp --key-command sets it.Nonevault kv get -field=key secret/instruction-mcp
INSTRUCTION_MD_SEAL_PASSPHRASEinstruction, instruction-mcpA person's passphrase: it unlocks their own key, registered on instruction.md, when no key file or command is given. instruction-mcp key init needs it to make a person's key (at least 12 characters).None(from your secret store)
INSTRUCTION_MD_SEAL_RECOVERYinstruction, instruction-mcpA person's recovery key, shown once when the key was made: it unlocks their own key when no key file, command or passphrase does.None(from your secret store)
INSTRUCTION_MD_PUBLIC_URLinstruction-mcpinstruction-mcp --http: the address people reach the company proxy at; its MCP endpoint is <public-url>/mcp. The same as --public-url.None: --http needs ithttps://mcp.acme.com
INSTRUCTION_MD_ALLOW_DOMAINSinstruction-mcpinstruction-mcp --http: email domains, separated by commas, whose people the proxy serves; added to each --allow-domain. A person's verified email must be at one of them.Every person instruction.md lets inacme.com,acme.co.uk
XDG_CONFIG_HOMEinstruction, instruction agentsThe base of the config folder: credentials.json, accounts.json and mcp-tokens.json are in its instruction-md folder.~/.config/home/ci/.config
XDG_CACHE_HOMEinstructionThe base of the cache folder, when INSTRUCTION_MD_CACHE is unset.~/.cache/tmp/cache
CODEX_HOMEinstruction agentsCodex's home: the runner trusts its agents' folders in the config.toml there, so Codex reads their project config.~/.codex/srv/codex
BROWSERinstructioninstruction login and instruction agents signin open the sign-in page with this command instead of the system's. none, false, 0 or an empty value opens no browser: the command prints the link instead.open (macOS), rundll32 (Windows), xdg-open (Linux); wslview in WSLfirefox
HOSTNAMEinstructionNames this machine in the default client title and in instruction watch's reports.The system's host namebuild-42
CLAUDE_CODE_MCP_SERVER_NAMEinstruction agentsSet by Claude Code when it runs a headersHelper: instruction agents credential takes it as the server when none is named.Unset outside Claude Codegithub
CLAUDE_CODE_MCP_SERVER_URLinstruction agentsSet by Claude Code when it runs a headersHelper: instruction agents credential takes it as the server's address when --url isn't given.Unset outside Claude Codehttps://api.githubcopilot.com/mcp/

Each row has an anchor made from its name, for example #instruction-md-token.

Example: config and cache in a job's own folder

A CI job or a container can keep the sign-in and the cache out of the home folder:

Shell
export XDG_CONFIG_HOME="$RUNNER_TEMP/config"
export INSTRUCTION_MD_CACHE="$RUNNER_TEMP/instruction-md-cache"
instruction whoami

Names that appear in samples but that no command reads

instruction agents create and instruction connect print INSTRUCTION_MD_CLIENT_SECRET as the place to keep an agent credential's secret, and their samples mint a token from it. No command reads that variable itself: your script or your CI job does, as in Publish and check from CI. The same goes for the token URL and client id you store beside it.

Variables the runner sets for each agent

instruction agents run starts each agent with its own environment: what the runner inherited, plus these (apps/agents-cli/src/fleet.ts):

  • INSTRUCTION_MD_FOLLOW: the address the agent follows (instruction://…).
  • INSTRUCTION_MD_DEPLOYMENT: the deployment's id. The agent's hooks report under it.
  • INSTRUCTION_MD_URL and INSTRUCTION_MD_ACCOUNTS, when the runner was given its own.
  • With --remote-control: TERM (kept if it is set and isn't dumb, else xterm-256color), COLUMNS=120 and LINES=40, for the terminal the session runs in.

The runner leaves out Claude Code's own session variables (CLAUDECODE, CLAUDE_PID, CLAUDE_EFFORT, CLAUDE_CODE_SESSION_ID, CLAUDE_CODE_BRIDGE_SESSION_ID and the other session, messaging and entry-point variables), so an agent started from inside a Claude Code session doesn't present itself as that session. With --remote-control, it also leaves out ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN and ANTHROPIC_BASE_URL: Remote Control needs a claude.ai sign-in, not an API key. A sign-in given on purpose with instruction agents accounts host is added after that. See The runner.

The agents' own sign-ins

instruction agents check and the runner look for these variables to tell whether an agent's app is signed in. The list is read from apps/agents-cli/src/setup.ts:

AppVariables
claude-codeCLAUDE_CODE_OAUTH_TOKEN, ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN
codexCODEX_API_KEY, OPENAI_API_KEY, CODEX_ACCESS_TOKEN

Give a runner's agents one of them with instruction agents accounts host <app> --env <VAR> --from-env <V> or --from-command <C>. See Servers, skills and accounts.

instruction eval and the Claude API

instruction eval runs an instruction's eval cases against Claude with your own credentials. It uses the Anthropic SDK, which reads ANTHROPIC_API_KEY, or the profile ant auth login keeps. --dry-run prints what each case would send and calls no model, so it needs neither. See Checks, evals and tests.

Files on your machine

The config folder is $XDG_CONFIG_HOME/instruction-md, or ~/.config/instruction-md when XDG_CONFIG_HOME is unset. That holds on Windows too: the tools use the home folder's .config, not %APPDATA%.

FileWritten byWhat it holds
credentials.jsoninstruction login, instruction agents login (the same sign-in), and every command that refreshes a tokenOne sign-in per server address (the issuer, the client id, the access and refresh tokens, when the access token expires, its scope, browser or device), and default: the server of the last instruction login. A token passed with --token or INSTRUCTION_MD_TOKEN is never written here.
accounts.jsoninstruction agents accounts set, accounts host, accounts removeWhat each MCP server's account means on this machine: a variable, a command, a sign-in, or your identity provider (XAA); and each agent app's own sign-in for the runner. Never a secret's value. Moved with INSTRUCTION_MD_ACCOUNTS.
mcp-tokens.jsoninstruction agents signin, instruction agents credential (when it refreshes)Sign-ins to other MCP servers: their access and refresh tokens. Sent only to the server each is for. Moved with INSTRUCTION_MD_MCP_TOKENS.

These three files are written whole or not at all: a new file beside the old one, then renamed over it. Each is written with mode 0600. Writing credentials.json also sets the folder to 0700. On Windows, where files have no such mode bits, the folder's mode isn't set.

Shell
ls -l "${XDG_CONFIG_HOME:-$HOME/.config}/instruction-md/"
Output
-rw------- 1 you you  412 Nov 22 10:04 accounts.json
-rw------- 1 you you 3120 Nov 22 10:02 credentials.json
-rw------- 1 you you  988 Nov 22 10:06 mcp-tokens.json

credentials.json has this shape. Don't edit it by hand: sign in again instead.

credentials.json
{
  "profiles": {
    "https://instruction.md/mcp": {
      "url": "https://instruction.md/mcp",
      "issuer": "https://instruction.md/auth/realms/instruction-md",
      "clientId": "instruction-cli",
      "accessToken": "<access token>",
      "refreshToken": "<refresh token>",
      "expiresAt": 1795430400,
      "scope": "openid profile email",
      "method": "browser"
    },
    "default": { "url": "https://instruction.md/mcp" }
  }
}

The cache

An instruction followed by its address rather than by a project (a managed hook, instruction agents hook … --follow, INSTRUCTION_MD_FOLLOW) keeps its copy in the cache: <cache>/follow/<first 16 hex digits of the address's SHA-256>/, with the same current.md and state.json a project has. <cache> is INSTRUCTION_MD_CACHE, else $XDG_CACHE_HOME/instruction-md, else ~/.cache/instruction-md. Deleting it is safe: the next read fetches the text again.

Key files

FileWritten byWhat it holds
instruction-md.key (or --file)instruction-mcp key init for an agent, key init --key-service for an organization's proxyThe private key that opens sealed instructions (imd-seal/1), mode 0600. It is written in the current folder and never overwrites a file that exists. See instruction-mcp.
instruction-key.json (or --out)instruction keygenAn Ed25519 key pair, mode 0600, refused if the file exists unless --force. Register its public half with instruction keys add. Releases on instruction.md are signed by the server with the organization's platform key, so this key doesn't sign them. See Signing and verification.

Files in a project

A project that follows an instruction has an .instruction/ folder at its root. Only follow.json and applied.json belong in the repository. The .gitignore the tools write there keeps current.md, state.json and given/ out. mcp.json, claude-settings.json and fleet.log are written only in the runner's agent folders, which aren't a repository:

.instruction/
.instruction/
  follow.json          committed: what the project follows
  .gitignore           current.md, state.json, given/
  current.md           the delivered text the hooks give
  state.json           what current.md is, and what each session was given
  given/               one marker per session and version given
  applied.json         committed: the entries instruction agents apply wrote
  mcp.json             the runner's agents: their MCP servers
  claude-settings.json the runner's agents: their Claude Code permissions
  fleet.log            the runner's agents: the last lines of their output

follow.json is described on How following works, which owns its keys. current.md holds the text an agent receives, never the authored source; it is written whole or not at all, so an agent never reads half a file.

The runner keeps .instruction-fleet.json in its --dir: which agent folders it made (it never deletes one it didn't make) and what it started in each.

Files written into the agents' apps

These are the files the commands write or merge into. Each command changes only its own entries and keeps the rest of the file.

CommandAppFiles
instruction agents follow <uri> --host HOST --write (the hooks)Claude Code.claude/settings.json
Codex.codex/hooks.json
Qwen Code.qwen/settings.json
Gemini CLI.gemini/settings.json
Droid.factory/hooks.json
Devin.devin/hooks.v1.json (Devin also runs .claude/settings.json's hooks)
Antigravity.agents/hooks.json
Copilot.github/hooks/instruction-md.json
Cursor.cursor/hooks.json
Cline.clinerules/hooks/<Event>, one executable per event
Crush.crushrc
instruction agents install <uri> --host HOST --as agent|skillClaude Code.claude/agents/<name>.md or .claude/skills/<name>/SKILL.md
Codex.agents/skills/<name>/SKILL.md
instruction agents applyClaude Code.mcp.json (servers), .claude/settings.json (allowed and denied tools), .claude/skills/<id>/SKILL.md; with --approve, .claude/settings.local.json
Codex.codex/config.toml (servers, enabled and disabled tools), .agents/skills/<id>/SKILL.md
instruction agents runCodexA block in $CODEX_HOME/config.toml (default ~/.codex/config.toml) that trusts the runner's agent folders, so Codex reads their project config
instruction watch --out FILE [--block]AnyThe file you name, whole, or with --block only its own fenced region of it. --rule writes a Cursor rule (.cursor/rules/instruction-md.mdc)

Kiro and Junie take their hooks by hand: follow prints what to add. instruction agents follow … --managed prints an organization's managed settings (Claude Code's managed-settings.json, Codex's requirements.toml) and writes nothing. See Claude Code, Codex and Servers, skills and accounts.

Operating systems

All three packages need Node.js 20.19 or later.

FeatureLinuxmacOSWindows
instruction: offline commands, registry commands, loginYesYesYes. No mode bits on the sign-in files
instruction login opening a browserWith a display (DISPLAY or WAYLAND_DISPLAY), or WSL. Over SSH or with no display, use --deviceYesYes
Hooks (instruction agents hook)YesYesYes. Copilot's hook file carries a PowerShell form
Runner (instruction agents run)YesYesYes, without --remote-control
Remote Control (run --remote-control)Yes (needs script from util-linux)YesNo: there is no script to give the session a terminal
Account commands (accounts set --command)/bin/sh -c/bin/sh -ccmd.exe /d /s /c
INSTRUCTION_MD_SEAL_KEY_COMMAND in instruction and the hookssh -csh -cNeeds sh on the PATH
instruction-mcp --key-commandsh -csh -ccmd /c

If it doesn't work

What you seeWhyWhat to do
A command signs in again, or says you aren't signed in, in a container or CI jobXDG_CONFIG_HOME or the home folder differs from where you ran instruction loginSet XDG_CONFIG_HOME to the folder that has instruction-md/credentials.json, or pass INSTRUCTION_MD_TOKEN
Commands go to another server than you expectThe last instruction login --url became the default, or INSTRUCTION_MD_URL is setinstruction login --url https://instruction.md/mcp, or unset the variable
… is not JSON for accounts.jsonThe file was edited by handFix the JSON, or remove the file and set the entries again with instruction agents accounts set
… isn't an imd-seal/1 key fileINSTRUCTION_MD_SEAL_KEY_FILE or the key command's output isn't a key filePoint it at the file instruction-mcp key init wrote; a key command must print that file's JSON and nothing else
Still stuckAsk us, with the command, its output and your operating system

Last checked against the product:

Was this page helpful? Report a problem