Sealed instructions for developers
This page is for developers who connect agents and AI apps to a sealed workspace, and for the platform team that runs the company proxy. A sealed workspace keeps its instructions encrypted on its people's devices and in your proxy: instruction.md stores and delivers them, versions and all, but can't read them.
Plans On Team and Enterprise
Before you start
- The people side is done in the editor. Each person sets up their encryption key in Your account ▸ Security ▸ Encryption key, an admin seals a new, empty workspace in Settings ▸ Workspaces (Seal this workspace ▸ Seal workspace), and people who hold the key give it to the others (Give the key). Sealed workspaces explains it in plain words.
- Sealed text is opened only where a key is held: the editor,
@instruction.md/mcp(theinstruction-mcpcommand), and the followers ofinstruction.mdand@instruction.md/agents. Everything else gets the encrypted envelope. @instruction.md/mcpneeds Node.js 20.19 or later. It signs in the way theinstructioncommand does: the sign-ininstruction loginstored, or a token in--tokenorINSTRUCTION_MD_TOKEN.
Every flag of instruction-mcp is on instruction-mcp command reference.
How each kind of key unlocks
| Who | Its key | Unlocked here by |
|---|---|---|
| A person | made in the editor (or by instruction-mcp key init with a passphrase) |
a passphrase (INSTRUCTION_MD_SEAL_PASSPHRASE) or the recovery key (INSTRUCTION_MD_SEAL_RECOVERY). A passkey or security key works only in the browser. |
| An agent | instruction-mcp key init, signed in as the agent |
its key file (--key-file, INSTRUCTION_MD_SEAL_KEY_FILE), or a command that prints it (INSTRUCTION_MD_SEAL_KEY_COMMAND) |
| A key service | instruction-mcp key init --key-service, by an organization admin |
its key file or a key command, in the company proxy only |
A key opens a workspace only once someone who holds the workspace's key has given it to that key. The editor shows people and agents who are waiting; key services are given the key with a tool call (below).
Give an agent its own key
An agent (a CI job, a bot, a runner) gets a key of its own, in a file only it can read.
Sign in as the agent
Make the agent's credential in Developer ▸ API keys (an organization owner or admin; see Agent credentials), then trade its client id and secret for a token.
key initmakes an agent's key when the account it is signed in as isn't a person.Shellexport INSTRUCTION_MD_TOKEN=$(curl -s \ -d grant_type=client_credentials -d client_id="$CLIENT_ID" -d client_secret="$CLIENT_SECRET" \ https://instruction.md/auth/realms/instruction-md-agents/protocol/openid-connect/token | jq -r .access_token)Make the agent's key
Shellnpx -y @instruction.md/mcp key init --file agent.keyOutputyour key: 5021 BB26 F3EB 27A6 41D2 570E 7422 3D5A 26D5 9A92 in agent.key (keep it secret: it opens what this agent may read) your recovery key (shown once, keep it somewhere safe): <recovery key> Next: someone who holds a sealed workspace's key approves you (the editor shows you waiting).The file is written with mode
0600, and an existing file is never overwritten (--filedefaults to./instruction-md.key). Its public key is registered with instruction.md. The private key never leaves the file.Have someone give the agent the workspace's key
The agent needs a role in the workspace first: a key is given only to someone with a role in it. Then a person who holds the workspace's key sees the agent waiting in Settings ▸ Workspaces and chooses Give the key, after comparing the fingerprint with the one
key initprinted.Check it
Shellnpx -y @instruction.md/mcp key status --key-file agent.keyOutputyour key: 5021 BB26 F3EB 27A6 41D2 570E 7422 3D5A 26D5 9A92 unlocked hereWith a key file, "unlocked here" means the file is valid and readable. It isn't compared with the registered key, so compare the fingerprints yourself.
A token given with --token or INSTRUCTION_MD_TOKEN is used as it is, never refreshed. Agent tokens are short-lived: start the server with a fresh one, or restart it when instruction.md answers 401. A person's sign-in stored by instruction login refreshes itself.
A person can make their key outside the browser too, signed in as themselves:
export INSTRUCTION_MD_SEAL_PASSPHRASE='<at least 12 characters>'
npx -y @instruction.md/mcp key init The passphrase must be at least 12 characters. The key is registered with the passphrase and a recovery key, printed once; no file is written.
Connect an AI app on stdio
instruction-mcp without --http is an MCP server on stdio with the same tools, resources and prompts as https://instruction.md/mcp. It opens each sealed envelope in an answer with its key, and seals what it writes to a sealed instruction before it sends it. In any app that runs an MCP command:
{
"mcpServers": {
"instruction-md": {
"command": "npx",
"args": ["-y", "@instruction.md/mcp", "--key-file", "/home/you/.config/instruction-md/agent.key"]
}
}
} With your own key, unlocked by your passphrase, in Claude Code:
claude mcp add instruction-md -e INSTRUCTION_MD_SEAL_PASSPHRASE='<your passphrase>' -- npx -y @instruction.md/mcp Keep a passphrase in the app's secret or environment settings, not in a config file you share. Without a key, the server still runs, and sealed instructions pass through still sealed. It says so on standard error, at start ("no key — sealed instructions pass through still sealed") and at the first sealed answer.
What it does to each call:
| Call | On a sealed instruction |
|---|---|
| Any tool answer | each envelope this key opens is replaced by its text, and a mediaType of application/vnd.instruction-md.sealed+json becomes text/markdown |
| A resource read | the envelope is replaced by its text, as text/markdown; variant=instruction, with _meta md.instruction/resolution: "unsealed", md.instruction/plaintextDigest and md.instruction/sealedAuthor |
instructions_create with content |
made with its title only (title, else the first # heading, else "Untitled"), then the text sealed as its draft; public becomes internal |
instructions_draft_replace |
the new text sealed and stored |
instructions_draft_edit |
the draft opened, the operations applied here, the result sealed. moveSection and duplicateSection are refused: do them in the editor, or send the whole text |
instructions_publish |
the draft sealed as the next version, chained to the latest; the sealed bytes are kept for the confirmation (10 minutes on stdio) |
instructions_validate, instructions_diff |
run here, on the opened text |
Resource subscriptions and live updates aren't passed through yet. For live updates, connect to https://instruction.md/mcp alongside.
The CLI's followers and the hooks
The followers that open sealed text are the hooks (instruction agents hook), instruction agents install, instruction mcp --follow and the @instruction.md/agents/agent helper. They open the envelope with this machine's key before the follower sees it, so an agent gets the text, never ciphertext. The key comes from the environment of the app that runs them:
# Claude Code's hooks (and every other app's) read the key from the app's environment
export INSTRUCTION_MD_SEAL_KEY_FILE="$HOME/.config/instruction-md/agent.key"
claude
# the stdio server that serves the followed instruction as instruction://current
INSTRUCTION_MD_SEAL_KEY_FILE=/keys/agent.key instruction mcp --follow instruction://acme/support-agent@stable Where the key comes from, in order:
| Variable | What it is |
|---|---|
INSTRUCTION_MD_SEAL_KEY_COMMAND | A 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. |
INSTRUCTION_MD_SEAL_KEY_FILE | A 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. |
INSTRUCTION_MD_SEAL_PASSPHRASE | A 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). |
INSTRUCTION_MD_SEAL_RECOVERY | A person's recovery key, shown once when the key was made: it unlocks their own key when no key file, command or passphrase does. |
Without a key, the version is held, never applied as ciphertext, and the last good version stays (see How following works). The reason is:
read failed (hook): sealed: this instruction is encrypted, and this machine has no key for it (INSTRUCTION_MD_SEAL_KEY_FILE, INSTRUCTION_MD_SEAL_KEY_COMMAND, or INSTRUCTION_MD_SEAL_PASSPHRASE; npx @instruction.md/mcp key init) A sealed version has no platform signature, so a follower that requires one holds it as unsigned. The author's own signature is checked when the envelope is opened. See Signing and verification.
Run the company proxy
The same server runs as your company's own MCP endpoint, for example https://mcp.acme.com/mcp. People's AI apps connect there and sign in with instruction.md exactly as before: the proxy's OAuth metadata names instruction.md's sign-in. Each request goes to instruction.md with that person's own token, so instruction.md still decides who may read what. The proxy holds the organization's key service key and opens what each person may read. People need no key of their own.
Who can do this: an organization owner or admin makes the key service's key. Someone who holds a sealed workspace's key gives it to the key service.
Make the key service's key
instruction login --admin
npx -y @instruction.md/mcp key init --key-service --org acme --file ks.key --label mcp.acme.com the key service's key: 7A1C 09E4 5B22 C3D8 6F10 A9B7 44E2 0C5D 98F3 21AB
in ks.key (keep it secret: give it to the proxy as --key-file, e.g. a Kubernetes secret)
Next: give each sealed workspace's key to it (the editor's Encryption settings, or seal_wraps_add). An organization has at most 20 key services, one per proxy you run.
Give it each sealed workspace's key
The editor has no screen for key services yet, although key init mentions one. Give the key with the seal_wraps_add tool: unwrap the workspace's key with your own, wrap it to the key service, and send the wrap. This script does it, run by a person who holds the workspace's key, signed in with instruction login, with a passphrase on their key:
// give-key-service.mjs — node give-key-service.mjs acme ws_<id>
// npm install instruction.md @instruction.md/seal
import { registryConnection } from "instruction.md/cli/registry";
import { unlockWithPassphrase, unwrap, wrapTo } from "@instruction.md/seal";
const [org, workspaceId] = process.argv.slice(2);
const conn = await registryConnection([]);
if (!conn) throw new Error("sign in first: instruction login");
const call = async (name, args) => {
const r = await conn.client.callTool({ name, arguments: args });
if (r.isError) throw new Error(`${name}: ${r.structuredContent?.error?.message ?? r.content?.[0]?.text}`);
return r.structuredContent ?? JSON.parse(r.content[0].text);
};
// 1. your own key, unlocked with your passphrase
const mine = await call("seal_keys_get", {});
const record = mine.unlocks.map((u) => u.record).find((r) => r.method === "passphrase");
if (!record) throw new Error("add a passphrase to your key first (Your account ▸ Security ▸ Encryption key)");
const me = await unlockWithPassphrase(record, process.env.INSTRUCTION_MD_SEAL_PASSPHRASE);
// 2. the workspace's key at its current epoch
const ws = await call("seal_workspaces_get", { workspaceId });
if (!ws.myWrap) throw new Error("you don't hold this workspace's key");
const key = await unwrap(ws.myWrap, me);
// 3. wrapped to each of the organization's key services that doesn't hold it yet
const { keyServices } = await call("seal_key_services_list", { orgId: org });
const holders = new Set(ws.recipients.map((r) => r.fingerprint));
const to = keyServices.filter((k) => !holders.has(k.fingerprint)).map((k) => k.public);
if (to.length) {
const r = await call("seal_wraps_add", { workspaceId, wraps: await wrapTo(key, to) });
console.log(`gave epoch ${r.epoch}'s key to ${r.added.join(", ")}`);
} else console.log("every key service holds it already");
await conn.client.close(); export INSTRUCTION_MD_SEAL_PASSPHRASE='<your passphrase>'
node give-key-service.mjs acme ws_<id> gave epoch 1's key to 7A1C 09E4 5B22 C3D8 6F10 A9B7 44E2 0C5D 98F3 21AB seal_wraps_add gives the current epoch's key only. When the workspace's key is rotated in the editor (Rotate key), the new epoch is wrapped to every key that holds the current one, the key services included.
Run it
The published image ghcr.io/instruction-md/mcp isn't public yet. Build the same image from the npm package with the Dockerfile it is built from:
ARG NODE_IMAGE=node:22.21.1-alpine3.22
FROM ${NODE_IMAGE}
ARG VERSION
RUN test -n "$VERSION" && npm install --global --omit=dev "@instruction.md/mcp@${VERSION}" && npm cache clean --force && rm -rf /root/.npm
ENV NODE_ENV=production NODE_OPTIONS=--enable-source-maps
USER node
EXPOSE 8780
HEALTHCHECK --interval=30s --timeout=3s CMD wget -qO- http://127.0.0.1:8780/health >/dev/null || exit 1
ENTRYPOINT ["instruction-mcp"]
CMD ["--http", "8780"] docker build --build-arg VERSION=0.1.1 -t instruction-mcp:0.1.1 . Then run it with the key file. The container runs as uid 1000, and the root filesystem can be read-only: it writes nothing.
sudo chown 1000:1000 /secure/ks.key # the container runs as uid 1000; keep the mode 0600
docker run -d -p 8780:8780 --read-only \
-v /secure/ks.key:/keys/ks.key:ro \
-e INSTRUCTION_MD_PUBLIC_URL=https://mcp.acme.com \
-e INSTRUCTION_MD_SEAL_KEY_FILE=/keys/ks.key \
-e INSTRUCTION_MD_ALLOW_DOMAINS=acme.com \
instruction-mcp:0.1.1 Or without a container:
instruction-mcp --http 8780 --public-url https://mcp.acme.com --key-file ks.key --allow-domain acme.com instruction-mcp: serving https://mcp.acme.com/mcp on :8780 as key service 7A1C 09E4 5B22 C3D8 6F10 A9B7 44E2 0C5D 98F3 21AB --http needs --public-url and a key service's key; a person's or agent's key is refused. --allow-domain (or INSTRUCTION_MD_ALLOW_DOMAINS, comma-separated) serves only accounts whose email, verified by the identity provider as instruction.md reports it, is at one of your domains. It keeps outsiders off your proxy. It isn't your access control: instruction.md still checks each person's access to each instruction.
--public-url can also come from INSTRUCTION_MD_PUBLIC_URL, as in the container above. --url (INSTRUCTION_MD_URL, default https://instruction.md/mcp) and --issuer (INSTRUCTION_MD_ISSUER, default <url's origin>/auth/realms/instruction-md) point the proxy at a self-hosted server and its sign-in.
Keep the key in a KMS or secret store
The key file is the proxy's one secret. Instead of mounting it, give a command that prints it at start: --key-command or INSTRUCTION_MD_SEAL_KEY_COMMAND. It runs through sh -c (cmd /c on Windows), has 30 seconds, and its standard output (at most 64 KiB) must be the key file's JSON. A command wins over a key file.
With Vault:
vault kv put secret/instruction-mcp key=@ks.key
instruction-mcp --http 8780 --public-url https://mcp.acme.com \
--key-command "vault kv get -field=key secret/instruction-mcp" With AWS KMS, keep only an encrypted copy of the key file:
aws kms encrypt --key-id alias/instruction-mcp --plaintext fileb://ks.key \
--query CiphertextBlob --output text | base64 -d > ks.key.enc
shred -u ks.key The image has no AWS CLI, so add it in an image of your own, and run that with the command:
FROM instruction-mcp:0.1.1
USER root
RUN apk add --no-cache aws-cli
USER node docker build -t instruction-mcp:0.1.1-kms -f kms.Dockerfile .
docker run -d -p 8780:8780 --read-only --tmpfs /tmp -e HOME=/tmp \
-v /secure/ks.key.enc:/keys/ks.key.enc:ro \
-e AWS_REGION=eu-central-1 \
-e INSTRUCTION_MD_PUBLIC_URL=https://mcp.acme.com \
-e INSTRUCTION_MD_SEAL_KEY_COMMAND="aws kms decrypt --ciphertext-blob fileb:///keys/ks.key.enc --query Plaintext --output text | base64 -d" \
-e INSTRUCTION_MD_ALLOW_DOMAINS=acme.com \
instruction-mcp:0.1.1-kms The container needs AWS credentials that may call kms:Decrypt on the key, such as an instance role. The writable /tmp is for the AWS CLI's own files; the proxy writes nothing.
On Kubernetes
Push the image to your own registry first. runAsUser must be numeric: the image names its user node, and with runAsNonRoot alone the kubelet refuses the pod.
apiVersion: apps/v1
kind: Deployment
metadata: { name: instruction-mcp }
spec:
replicas: 1 # more: route each person to one replica (see Replicas)
selector: { matchLabels: { app: instruction-mcp } }
template:
metadata: { labels: { app: instruction-mcp } }
spec:
securityContext: { runAsNonRoot: true, runAsUser: 1000, runAsGroup: 1000, fsGroup: 1000 }
containers:
- name: proxy
image: registry.acme.com/instruction-mcp:0.1.1
ports: [{ containerPort: 8780 }]
env:
- { name: INSTRUCTION_MD_PUBLIC_URL, value: https://mcp.acme.com }
- { name: INSTRUCTION_MD_SEAL_KEY_FILE, value: /keys/ks.key }
- { name: INSTRUCTION_MD_ALLOW_DOMAINS, value: acme.com }
volumeMounts: [{ name: key, mountPath: /keys, readOnly: true }]
securityContext: { readOnlyRootFilesystem: true, allowPrivilegeEscalation: false }
readinessProbe: { httpGet: { path: /health, port: 8780 } }
volumes:
- name: key
# kubectl create secret generic instruction-mcp-key --from-file=ks.key
# 0440 with fsGroup 1000: readable by the container's group only (0400 is unreadable for uid 1000)
secret: { secretName: instruction-mcp-key, defaultMode: 0440 }
---
apiVersion: v1
kind: Service
metadata: { name: instruction-mcp }
spec: { selector: { app: instruction-mcp }, ports: [{ port: 80, targetPort: 8780 }] } TLS is yours: put the proxy behind your ingress or load balancer, so https://mcp.acme.com reaches port 8780. The proxy speaks plain HTTP.
curl -s https://mcp.acme.com/health {"ok":true} | Endpoint | Answer |
|---|---|
POST /mcp |
the MCP endpoint (stateless, JSON responses); 401 without a token or with a refused one, 403 when the account's domain isn't allowed, 400 for a body over 4 MiB or not JSON |
GET /.well-known/oauth-protected-resource/mcp (also without /mcp) |
the protected-resource metadata, naming instruction.md's sign-in |
GET /health |
{"ok":true} |
| any other path | 404; another method on /mcp, 405 |
Replicas
The proxy keeps no MCP sessions, so any replica can answer any call, with one exception: a release. instructions_publish seals the version, and instruction.md asks for confirmation. The sealed bytes are held in that replica's memory, in the person's cached connection, which lasts 4 minutes from their first call on it. The confirming call must reach the same replica in that time. Otherwise instruction.md refuses it ("this confirmToken is for a different call") and nothing is released. Run one replica, or route each person to the same replica (for example by hashing the Authorization header at your ingress), and confirm promptly.
Connect people's apps
People add https://mcp.acme.com/mcp as a remote (HTTP) MCP server and sign in with instruction.md. In Claude Code:
claude mcp add --transport http instruction-md https://mcp.acme.com/mcp What works on a sealed instruction
instruction.md can't read the text, so what needs the text on the server refuses a sealed instruction, saying where it is done instead (forbidden, details.reason: "sealed"). The editor and instruction-mcp do the same work where the text is opened.
| Works | Refused on the server |
|---|---|
| reading versions and drafts (as envelopes), versions, refs and their moves, revoking a version | checks (instructions_checks_run), validating or diffing the stored text, and comparing a proposal with it |
releasing (instructions_sealed_publish, which instruction-mcp and the editor call) |
instructions_publish, and the draft-edit tools on the stored draft |
| followers, bindings and the agents' reports | resolving a delivery (instructions_versions_read with resolve: true) |
| sealed agent conversations (the runner seals them with its key) | public visibility, read links, the instruction's web page |
| the assistant, search inside the text, duplicating and forking, moving between workspaces |
A few things more:
- A sealed instruction needs its title when it is made: the title isn't encrypted, and it isn't read from the text.
- A ref gated on checks can't take a sealed version: the server can't run its checks.
- A sealed object is at most about 2 MB.
- One person edits a sealed draft at a time. A save that comes after someone else's is refused as a conflict.
- Only an empty workspace can be sealed. An existing instruction can't be moved into one yet.
- A scheduled release of a sealed instruction fails when it runs: the server can't seal the draft. Release it yourself, through the editor or
instruction-mcp.
If it doesn't work
| What you see | Why | What to do |
|---|---|---|
Answers show a JSON object with "seal":"imd-seal/1" |
the server has no key | give it --key-file, or set INSTRUCTION_MD_SEAL_PASSPHRASE or INSTRUCTION_MD_SEAL_RECOVERY in the app's environment; check with key status |
this key doesn't hold workspace ws_…'s key yet (instruction-mcp), or sealed: this key (…) hasn't been given the workspace's key yet (the CLI's followers and hooks) |
the key wasn't given the workspace's key, or not at this epoch | someone who holds it gives it (Give the key, or seal_wraps_add) |
key status says not unlocked here |
a passkey-only key can't unlock outside the browser | add a passphrase in Your account ▸ Security ▸ Encryption key, or use INSTRUCTION_MD_SEAL_RECOVERY |
instruction-mcp needs your sign-in (exit 3) |
no sign-in stored, no token | npx instruction.md login, or --token |
Every call fails with 401 after a few minutes |
an agent's token expired: a given token isn't refreshed | get a fresh token and restart the server |
… exists: not overwritten |
key init never replaces a key file |
choose another --file |
isn't a key service's key (instruction-mcp key init --key-service) |
--http takes only a key service's key |
make one with key init --key-service |
The container exits with EACCES: permission denied, open '/keys/ks.key' |
uid 1000 can't read the mounted file | sudo chown 1000:1000 the file, keep mode 0600 |
docker pull ghcr.io/instruction-md/mcp answers unauthorized |
the image isn't public yet | build it, as above |
this confirmToken is for a different call |
the confirmation reached another replica, or came too late | ask for the release again and confirm promptly; see Replicas |
403 this organization's proxy doesn't serve your account |
the account's email domain isn't allowed | check --allow-domain |
… is sealed: instruction.md can't read it, so … runs where it is unlocked |
a server-side tool met a sealed instruction | do it in the editor or through instruction-mcp |
| Still stuck | Support |
Questions
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 hooks and instruction mcp --follow open the text with it, and the company proxy takes the same command as --key-command. See The CLI's followers and the hooks.
Can people use a passkey with instruction-mcp?
No. A passkey or security key unlocks only in the browser. Outside it, a person's key is unlocked with a passphrase or the recovery key; add a passphrase in the editor first.
Does the company proxy replace instruction.md's access checks?
No. Each request goes to instruction.md with the person's own token, and instruction.md decides what they may read. The proxy only opens what instruction.md lets them have, and --allow-domain keeps other accounts off it.
Can an agent read versions sealed before it was given the key?
Only versions of the epochs it was given. The key is given at the current epoch, so after a rotation a newly approved key can't open versions sealed under earlier epochs. See Sealed cryptography.
Why can't I make a sealed instruction public?
A public instruction is one anyone can read, and only key holders can read a sealed one. Sealed instructions are private or internal; asking for public is refused, and instruction-mcp turns it into internal.