Esta página aún no está traducida.

Developer FAQ

This page is for developers with a question about instruction.md's CLI, its MCP server, following, signing or self-hosting. Each answer is short and links the page that owns the fact. Questions about the editor, plans and accounts, in plain words, are in Questions and answers.

Jump to: Packages and commands · CI · Following and hooks · Signatures · Sealed instructions · The MCP server · The language · Agents and the runner · Organizations · Embedding and self-hosting

Packages and commands

What is the difference between instruction and instruction agents, and which package do I install?

instruction is the instruction.md package (npm i -g instruction.md). It writes, checks and releases instructions, signs you in, and runs watch and the stdio MCP server. instruction agents <command> hands the line over to @instruction.md/agents, which runs the agents that follow them: follow, install, run, apply, check, hook and more. instruction agents list, create, rotate and revoke are the exception: they are instruction's own agent-credential commands. See Which package does what.

Will my old npx instruction.md hook settings keep working?

Yes. instruction still accepts the commands that moved and hands them to the installed instruction-agents, or else to npx --yes @instruction.md/agents, with the arguments, standard input and output and the exit code unchanged. A hook that can't be handed over exits 0, as it would offline, so it never blocks a prompt. Write npx -y @instruction.md/agents hook <host> in new settings. See Renamed and moved commands.

Which environment variables does each command read?

The main ones are INSTRUCTION_MD_URL (the MCP server), INSTRUCTION_MD_TOKEN (a token instead of the stored sign-in) and XDG_CONFIG_HOME (where the sign-in and the accounts file are kept). The full list for instruction, instruction-agents and instruction-mcp, read from their code, is on Environment and files.

How do I export every version (zip or OCI)?

Run instruction export <id> --format zip for a zip with every version's text and record, or --format oci for an OCI image layout tagged vN and with the refs' names. Each version's record keeps its signatures. See Export every version.

CI

How do I get a non-interactive token for CI?

Plans On Pro, Team, and Enterprise

Create an agent credential under Developer ▸ API keys, or with instruction agents create. Keep its client id as a pipeline variable and its secret as a secret, and ask the token URL for a token with the client-credentials grant in the step that needs it. A token lasts five minutes and has no refresh token. See Agent credentials.

Why does instruction publish stop with exit code 7 in a pipeline?

A release asks first, and a job has no terminal to ask on, so it prints this asks first; nothing changed (run again with --yes to go ahead) and changes nothing. Add --yes. instruction revoke and a ref move ask the same way, and --yes agrees to them too. See Publish and check from CI.

How do I make stable follow latest automatically once checks pass?

Create stable first with instruction refs <id> set stable <version>, because it is never made for you. Then gate it: instruction refs <id> gate stable --require-checks --promote-from latest --after 1440 moves it to a version of latest that has stood there a day and passed its checks. Only a person sets a promotion, and it runs as that person. See Gate stable and Refs.

Following and hooks

Should I commit .instruction/follow.json, current.md and state.json?

Commit follow.json, so everyone on the project follows the same instruction, and applied.json with the files it lists. current.md, state.json and given/ are the machine's own, and .instruction/.gitignore keeps them out of git. See follow.json and Other files.

What happens to my agent when I'm offline or a version can't be verified?

The hook gives the last good copy, .instruction/current.md, and tries again at the next prompt. A version it can't apply, such as an unsigned one when requireSignature is on, is held, and the last good one stays. A hook never holds a prompt up; add --fail-closed where a session must not run with no copy at all. See Offline and Holds.

How do I keep an agent on one version, or on a tested one?

Follow one version, acme/support-agent@v3 or @ver_…, and it never changes. Follow a ref you move yourself, such as @stable, to choose when agents take a new version. stable is never created for you: run instruction refs <id> set stable <version> before anything follows it. See Refs and versions.

How fast does a new version reach a running Claude Code or Codex session?

At your next prompt, never in the middle of an answer. The hook reads at most every refreshSeconds (60 by default) and waits at most 1.5 seconds, so a release can take up to a minute to show. The new version is given marked as replacing the old one in full. See Claude Code and Codex.

Why doesn't my second agent get live updates? Does it still work?

Plans Community 1 · Pro unlimited · Team unlimited · Enterprise unlimited

On a plan with this limit, that many consumers at a time hold live updates for an organization's instructions, and another is refused with JSON-RPC -32025 and limit_reached. Reading is never limited, so the second agent still reads its instruction whenever it needs to, and takes a place once one frees. See The live-updates limit.

Signatures

Can I sign releases with my own key (--sign-with)?

No. Every version is signed with the organization's platform key, and a key you register can't sign versions. instruction publish --sign-with and instruction push --sign-with stop before they send anything, with exit code 2. See Signing with your own key.

What happens to agents when I revoke a version?

A revoke refuses a version a ref points at, so move every ref off it first. The version stays readable and marked revoked, and no ref can point at it again. A follower pinned to it holds its last good version. See Revoke a version.

Does a signed version keep its text private?

No. Signing proves who released the text; the server and anyone its visibility allows can still read it. To keep a text from instruction.md itself, put it in a sealed workspace. See Signed is not sealed.

How do I make a follower apply only signed versions?

Set "requireSignature": true in the follow file, or pass --require-signature to the setup or the hook. Signed in, the publisher's keys are discovered from instruction://pub/<owner>/keys.json; signed out, name them in keys, or the version is held. See Signatures.

Sealed instructions

How do I read a sealed instruction from the CLI, hooks or a proxy with a KMS key?

Give the machine its key in the environment: INSTRUCTION_MD_SEAL_KEY_FILE, or INSTRUCTION_MD_SEAL_KEY_COMMAND for a key a KMS or secret store prints. The CLI's followers and the hooks open the text with it, and the company proxy takes the same command as --key-command. Without a key, a sealed version is held, never applied as ciphertext. Sealed workspaces are in beta, not yet independently reviewed. See Sealed instructions for developers.

What doesn't work on a sealed instruction?

Anything that needs the text on the server: checks, instructions_publish and the draft-edit tools, the assistant, search inside the text, forking, public visibility and read links. These answer forbidden with details.reason sealed. A release goes through instructions_sealed_publish, which the editor and instruction-mcp call. See What works on a sealed instruction.

The MCP server

Why do I get 401 at /mcp, or why can't my host connect?

Every request to https://instruction.md/mcp needs a token, discovery and lists included; without one the answer is 401 with a challenge that names the sign-in. A host on the session protocol (an initialize, an Mcp-Session-Id, a 2025 version) is refused with 400: the server speaks MCP 2026-07-28 only. Connect such a host through instruction mcp. See Troubleshooting and Sign-in, scopes and tokens.

Why can't my AI app see the organization tools?

They need the scope org:admin, which the server never names in its metadata, so a host gets it only when it asks for it by name and the person agrees. A host that named its scopes without it must be removed and added again. No agent or service credential can have it; on the command line, run instruction login --admin. See org:admin.

What does version_conflict mean, and is a retried create or publish safe?

version_conflict means the thing you edit changed since you read it: read again with details.reread, and redo your change on what you read. A create with an idempotencyKey answers what the first call made for 24 hours, so it is safe to send again. instructions_publish takes no key, but releasing a text equal to the latest version is refused with conflict, so a retry never makes two versions. See Contracts.

What are the instruction://, me:// and org:// addresses, and which can I subscribe to?

instruction:// reads instructions, their versions and their views; me:// is your own (for a person only); org:// is an organization's, and its administering views need an admin. Subscribe to an instruction's id form, instruction://ins_… or instruction://ins_…@<ref>: the owner/name form is never notified. See Resources and addresses.

How do I receive release events by webhook?

Subscribe an HTTPS endpoint with events/subscribe to md.instruction.releases. The gateway first sends a verification challenge your endpoint echoes back, then POSTs each event signed the Standard Webhooks way, retrying for about 15 minutes. A subscription lasts an hour unless you ask for between 5 minutes and 24 hours; renew it before refreshBefore. See Live updates, events and webhooks.

The language

Does naming a tool in an instruction give the agent access to it?

No. tools, allow and deny describe intended use; access comes from the host, the credential behind each account and the organization's policy. instruction agents apply writes allow and deny as Claude Code's or Codex's own permission rules, but a host that ignores them can still call a tool its credential allows. See Naming a tool never grants access.

Which parts of my instruction does the agent not receive?

The front matter, the backmatter (notes, sources), comments, and a block's id, class and style. The front matter's parameters only give values to the body. See What is never delivered and What an agent receives.

Does a workflow in my instruction run by itself when I publish it?

No. instruction.md keeps a workflow, checks it and draws it, and never runs it. It runs only in a program built to run workflows, which refuses a workflow with a kind of step it can't run. See Workflows, explained and Workflow node reference.

Can an instruction let an agent spend money?

Only inside a host that pays and whose operator has turned spending on. The instruction's allowance then limits what the agent may spend, and can never widen what the host allows. instruction.md itself never pays. See Allowances.

How do I validate my own parser against the specification?

Run the specification's conformance vectors against it. instruction test <dir> runs the source, resolution and text vectors with instruction.md's own reader, and prints nothing about the model, policy and workflow cases, which you run with your own harness. See Run the conformance vectors.

Agents and the runner

How do I give an agent keys for its MCP servers without putting them in the instruction?

The instruction names an account; each machine says what it means with instruction agents accounts set <server>@<account>, from a variable (--env), a command that prints the key (--command, such as Vault or 1Password), or a sign-in (--oauth). The entries live in ~/.config/instruction-md/accounts.json, readable by you only, and no command prints a value. See Say what each account means on this machine.

How do I fix Needs sign-in on a deployed agent?

The agent wasn't started because a sign-in is missing for its app or one of its servers. Run the command Settings ▸ Deployments shows, on that machine, as the runner's user, then check with instruction agents check --fleet. The runner starts the agent on its next pass. See Servers, skills and accounts.

How do I run the runner as a service, and what does Remote Control need?

Plans On Pro, Team, and Enterprise

Run instruction agents run as a systemd service with --restart-on-exit for agents that stay up, or from cron with --once for tasks that end. Remote Control (--remote-control) needs Claude Code signed in with a claude.ai account on a plan that has it, not an API key, on Linux or macOS, with the task as claude -p "…" and a runner that keeps running. See Keep it running and Remote Control.

Organizations

How do I allow only our approved MCP servers and block a tool?

Plans On Pro, Team, and Enterprise

Add the servers as integrations, then allow or block their tools with orgs_integrations_tools_set; blocked tools join the deny rules instruction agents apply writes. To restrict every instruction to the organization's integrations, set the policy key integrationsOnly, which has its own plans (below). The decision travels in the served text as host-integrations. See Integrations and The integrations policy.

Plans On Team and Enterprise

How do I connect Okta or Entra ID: a people directory or SCIM?

A people directory is pulled by instruction.md (orgs_people_directories_add), so its people can be mentioned as you write; its credential is used once and never kept. SCIM is pushed by your identity provider to the organization's SCIM base URL with a token from orgs_scim_tokens_create, which only owners make, at most 5 working at a time. Each has its own plans, below. See SCIM and people directories.

Plans On Pro, Team, and Enterprise

Plans On Team and Enterprise

Embedding and self-hosting

How do I show an instruction on my website, and does the renderer track readers?

Add one script tag and an <instruction-md> element with the text, or with src pointing at a file or a public instruction's web address. The renderer sends no cookies or credentials, and loads only from your own site, instruction.md and the hosts you allow; images are off until you add allow-images, because an image is a request to its server. See Embed and preview.

Can I self-host, and do I need an MCPG licence?

Yes: the production charts run in your own Kubernetes cluster, and deploy/k8s/stack/up.sh runs them locally in k3d. The platform source is under the Business Source License 1.1, which lets you run and change it for your own use but not offer it as a competing hosted service. More than one gateway replica, clustered on NATS, needs an MCPG licence; the local stack runs on MCPG's free non-production grant. See Self-hosting.

How do I report a security vulnerability?

Use the form on Contact us and choose "Security". A person reads every message. Please give us time to fix the problem before telling anyone else.

Last checked against the product:

Was this page helpful? Report a problem