Orchestrator drives tools that edit files and run commands. These are the boundaries it enforces and the ones it leaves to you.
| Actor | Credential | Can |
|---|---|---|
| Owner (the office UI) | owner token — random, stored hashed; plaintext only in ~/.orchestrator/server/owner-token (0600) |
everything in the REST API and client WebSocket |
| Host agent | host credential issued at enrollment — stored hashed on the server, plaintext only in the agent's config.json (0600) |
report its own sessions and hooks, answer RPCs. It cannot read or change other hosts' sessions: every message is checked against the connection's host id |
| Worker (a Claude Code session) | MCP bearer token — per launch, revoked when the session is relaunched | call the Orchestrator MCP tools as its own employee. Identity comes from the token, never from tool arguments |
Foreman (the one worker whose employee has the foreman role) |
the same per-launch MCP bearer token | additionally the foreman tools: read the office and employees' terminal screens (members' own employees included, while their computer is connected), answer employees' questions, tell them what to do next, assign and create tasks, escalate to the owner. Never an approval — see The foreman |
| Hook process | per-session hook token over a 0600 unix socket | post hook events for its own session |
Unauthenticated requests get 401; a client WebSocket without the owner token is closed (4003); an agent with an unknown or revoked credential is rejected.
Enrollment is explicit: a one-time token (expiring, single-use, hashed at rest) is created by the owner and traded for a host credential. Revocation is immediate: the credential is invalidated and the connection is cut; the host's tmux sessions are untouched.
Codex uses a private per-session home and a reference to the local host account’s file-backed login. The host confines native Codex writes to private scratch space and disables approval elevation. Plain-text files can be listed, read and written through a separate tool service scoped to the selected directory. It refuses paths outside the folder, hidden paths, likely credential names, symbolic and hard links, and the office's own files on the machine (the agent's and the server's homes, the session's own folder included — officeRoots); a deny rule for reading or editing takes the whole corresponding tool away. Native shell, web search and permission elevation are switched off by configuration — and because that rests on configuration keys a Codex version could ignore, the runner stops the worker at the first command, web search, image from the disk or file change outside its scratch folder (forbidden in codex-runner.ts; tests: apps/host-agent/test/codex-files.test.ts, codex-runner.test.ts, tests/e2e/64-codex-runtime.test.ts). The office also rejects file attachments by path and vault secret reads using the session’s MCP credential. A Codex worker on a personal host uses the existing member-room access checks. See Codex workers.
MOVE.md. A move lets the office read a folder off one machine and write a new one on another, through move.* RPCs of the machine's agent. What bounds it, on each machine (HostAgent.movable, apps/host-agent/src/move.ts):
- Packed only from inside the machine's allowed roots, never a whole allowed root or the home folder, never a folder that holds or is inside the office's own files (the agent's home, a server's home). That is no more than the office could already have an employee there read; on a member's computer the member's allowed roots are the fence, as for everything else.
- The conversation taken along: only the files of the conversations named (by id, of the employee's own sessions) and the folder's
memory/, from the Claude account folder of the employee (inside the home folder, as for a launch). - Written only as a new folder inside an allowed root (never over one that exists) and as conversation files that are not there yet; a move's own files only in
<agent home>/moves/<id>/, by fixed names; pieces only in order; every file checked by SHA-256 before anything is unpacked. A failure removes what was half made. - Nothing of the move is kept on the server; its files are removed on both machines when it ends.
.envand other secrets in the folder go along: that is what was asked for ("everything"). The vault is the office's and does not move.
- The server listens on
127.0.0.1by default. It refuses a non-loopback address without TLS (--tls-cert/--tls-key) unless--allow-insecure-remoteis given for a TLS-terminating proxy. - The agent CLI refuses to enroll against a non-TLS, non-loopback URL unless
--insecureis passed. - Hosts connect outward. Nothing listens on a host except the agent's unix socket.
- Terminal access is bound to registered sessions. The agent offers no "run this command" or "open a shell" RPC; the only arbitrary command it runs for the server is a project's verification command, in an allowed directory, and that can be switched off per host (
allowVerify: false). - Existing sessions: the office can only attach tmux panes that are running Claude Code (
remoteAttach: "claude", the default). A shell pane attached to the office would be a remote shell for the owner, so that requires eitherorchestrator-agent attachrun on the machine itself, orremoteAttach: "any"in that host's config."none"disables office-initiated attach entirely. - Input ownership is enforced on the server. One controller per session; an observer's keystrokes are dropped by the gateway regardless of what the UI does. Control is released automatically when the controller disconnects.
- Taking control, releasing it and interrupting are written to the audit log. Keystrokes are not logged.
- Terminal streams and monitor frames are never persisted.
- A goal's command to check by runs on the employee's machine, in their folder, outside Claude Code's permissions (no deny rules, no high-risk hold) — as a project's verification command does, and given by the same people: whoever may give that employee work. An employee cannot give one (
set_goaltakes only words; a check from an employee is refused), so setting yourself a goal is never a way past a permission. The machine'sallowVerify: falseswitches it off with verification. A visitor is not sent anybody's goal. - Commands in the background. The machine's agent reads its own user's process table (
ps -u <that user>) every two seconds, and sends the office only the commands of the shells Claude Code started for a session the office tracks — the same commands its hooks send anyway (cut to 4,000 characters, at most 20 a session). The office keeps of them only what is shown: Claude Code's description of the command, or the command itself with secrets taken out (redactSecrets), and since when — on the session's record, which a visitor is sent as they are sent the activity line. A report about a session of another machine is ignored.
- Signing in from the office (
ACCOUNTS.md): the machine runs Claude Code's own sign-in in a terminal apart from the employees'; an owner's window shows its text and passes on what is typed. The office handles the address of the sign-in page and the single-use code on their way, and keeps, logs and audits neither; the token Claude Code receives stays in its folder on the machine. Owners only. - A person's own character (
docs/CHARACTER.md) is the one thing a visitor can change: their own look, throughPUT /api/me/character, keyed by who they are — never anybody else's. What is sent is cleaned before it is kept or passed to other windows (cleanAppearance: known choices,#rrggbbcolours, numbers within range; everything else dropped), so a look cannot carry text, markup or oversized values to other people's screens (tested:tests/e2e/62-character.test.ts,packages/contracts/test/appearance.test.ts). - An API key of another service (Z.AI, DeepSeek, or the key of an OpenAI proxy on the machine) goes from an owner's window to the machine and is written into that account's
settings.jsonthere (mode 600). The office does not keep it and nothing it says or records contains it (tested:tests/e2e/51-account-sign-in.test.ts). Anybody who can read that user's files on that machine can read the key — as with a Claude login. The address of such a service must be https; plain http only to a proxy on that very machine (localhost, 127.x, [::1]), so nothing leaves it unencrypted. - The office never moves an employee from one service's models to another's by itself.
How much an employee may do without asking is one of three levels — Standard, Auto, Unrestricted — and each is expressed in Claude Code's own permission system and nothing else. (Until 2026-11-13 there were six; Restricted, Supervised and Autonomous were removed on the owner's word — DECISIONS.md, "Three levels". Whoever was on one of them was put on Standard when the office next started, on the record as autonomy.three_levels; nobody can be put on one again: POST/PATCH /employees and the host agent's create refuse a level that is not one of the three.)
| Level | Permission mode | Pre-approved | Denied |
|---|---|---|---|
| standard | acceptEdits | read-only git, git add/commit/merge, common test commands |
— |
Whoever is hired without a level being named is on Standard, whatever their role. No level is read-only. What somebody may not touch is said in their own denied tools (the profile, "Always denied tools"), in their role's — a foreman and a team lead cannot edit files at any level — or in the project's deny rules.
Plus project policy.allow / policy.deny, plus the employee's own lists. bypassPermissions is used for one level only — unrestricted, below — and never for any other.
| auto | auto | the above plus package managers, interpreters, build tools | — (Claude Code's auto mode decides) |
Auto. An employee on auto runs in Claude Code's own auto permission mode: its safety classifier decides what may run, so you are not asked for permission — only for decisions (ask_boss). New hires from the short hire form default to it. Two things follow from "do not ask me": the workspace-trust prompt for the folder you put them in is answered for you (recorded in the audit log as trust.auto_accepted), and nothing is surfaced as an approval unless it matches the high-risk list below. That last safeguard can be switched off in Settings → Employees ("On Auto, still ask me before high-risk commands"); the change is audited. The bypass mode is still never used.
| unrestricted | bypassPermissions | — (nothing is checked) | — (nothing asks; the high-risk list is held by the office, unless the owner switched that off) |
Unrestricted — the owner's default since 2026-11-11. An employee on unrestricted runs in Claude Code's bypass-permissions mode: Claude Code checks nothing and asks nothing. Claude Code's own words for it: "bypassPermissions offers no protection against prompt injection or unintended actions", and "Only use this mode in isolated environments like containers, VMs, or dev containers without internet access". The office's machines are not such an environment: they hold the vault and keys to production, and employees read web pages, tickets and customers' text. The owner chose this knowingly (the alternatives — allowing a refused action once, telling auto mode which infrastructure is the office's — were put to them first); it is written here so that nobody takes it for an oversight. What still stands in this mode:
- The office's high-risk list. The same patterns as at every level (pushes, hard resets, broad
rm -rf,sudo, deploys, publishing, piping downloads into a shell, reading key files, …). Claude Code would ask nobody, so the host agent holds the call itself until the owner answers in the office, and refuses it if no answer comes — there is no prompt to fall back to. The gate does not depend on the agent staying up: a hook that finds no agent (it is being restarted, as at a deploy) tries again for 45 seconds and is taken up by the agent that comes back, with the same request still open in the office; and if no agent comes back, a command (Bash) of a session in this mode is refused by the hook itself rather than run unchecked. (Until 2026-11-11 a held command ran when the agent was restarted while it waited;DECISIONS.md, "The hook outlives the agent". A session started before that fix is started again once to get the new hooks.) What this still leaves: tools other thanBashare not held back while the agent is away, and the refusal is made by a shell command in the session's own settings file, which the session's user could edit — it guards against the office's own restarts, not against the machine's owner. The switch On Auto, still ask me before high-risk commands (Settings → Employees) applies to this level too: off means nothing at all stands between an employee and such a command. - The owner can switch that list off for Unrestricted (Settings → Employees, "On Unrestricted, still ask me before high-risk commands";
OwnerSettings.unrestrictedAsksHighRisk, audited assettings.changed). Then nothing stands between an Unrestricted employee and a push, asudo, a deploy, a broad deletion or a credential file: what it runs, runs, and nobody is asked — including when the employee was steered by something it read. It is switched on in a new office; an office that never touched it follows the Auto switch, as before it existed. Off takes effect at once: a session that is already running is still held by its machine, and the office answers allow at once and writes it down (highrisk.not_heldin the audit log, with what ran); a session started afterwards has no list. Back on, sessions started without the list are started again between turns. A machine whose agent is older than this switch does not say what it holds a command for (and one older than Unrestricted answers "ask", which Claude Code shows as its own prompt in the terminal): a session there that was started with the list is started again once, between turns, without it (SessionRegistry.restartDue). The same now happens to a running Auto session when the Auto switch is turned off. - The office's own files on a machine stay fenced off whatever the switch says (
HostAgent.officeFiles): a command that names them is held for the owner, a file tool is refused. - The project's deny rules (
policy.deny) and the employee's own disallowed tools: Claude Code applies deny rules in every mode. - Who may give it: owners only (
access.ts). The office itself never raises anybody to it (its ceiling for raising autonomy by itself is standard). - Claude Code's warning at the first start of an account in this mode ("…you accept all responsibility…"). Until 2026-11-13 it was put to the owner in the office each time and never answered by the office. The owner then accepted it once for all ("this too should pass by itself"): with Settings → Employees → "Answer Claude Code's start-up questions for me" on (it is, unless switched off) the office chooses "Yes, I accept" itself — only for an employee whom an owner put on Unrestricted (nobody else can), only on the office's own machines, and each time on the record (audit
bypass.auto_accepted, and a line in the feed). On a member's own computer it is still asked; with the switch off it is asked everywhere, as before. - Claude Code's menu after a refused turn ("Stop and wait / Wait here / Switch to usage credits") is answered by the office only with "Stop and wait for limit to reset"; "Switch to usage credits" is never chosen — it spends money — and the menu's options are read from the screen, never pressed blind (
menuKeys). - Employees setting models (
set_model): model and effort only — no level, no account; not the foreman; not across a member's own computer; with a reason in the audit log. A model is not a permission: what an employee may run is the same on every model. - The workspace-trust question ("Is this a project you created or one you trust?") for the folder an employee was put in is answered "yes" by the office for every level with the same switch on (audit
trust.auto_accepted); with it off, only for Auto and Unrestricted, as it was. Trusting a folder lets Claude Code read that folder's own settings — its hooks and MCP servers among them: whoever chooses a folder for an employee is choosing to run what that folder's settings say. - The question about files a CLAUDE.md imports from outside the folder ("Allow external CLAUDE.md file imports?") is answered "Yes" under the same rule and switch (audit
imports.auto_accepted, with the files named; since 2026-11-20). Those files are read into the employee's instructions: whoever chooses the folder also chooses what its CLAUDE.md pulls in from elsewhere on the machine. Claude Code advises never allowing it for third-party repositories; the office cannot tell those apart, so a third-party repository should not be given to an employee with the switch on. - Not for SDK-managed workers (they get auto), and never with
CLAUDE_CODE_EVEN_MORE_DANGEROUSLY_SKIP_PERMISSIONS: Claude Code's last guard, the prompt before removing a critical path, stays. - A member's own computer is that member's to decide: the one-time move of employees from auto to unrestricted was made on the office's own machines only. What is gone in this mode: every permission prompt; auto mode's safety check (so "allowing once what Claude Code refused", below, never comes up); any protection against an instruction hidden in something the employee reads.
High-risk commands always escalate (for auto and for unrestricted: unless you switched that off — one switch each). A PreToolUse hook on the host matches shell commands against a pattern list (pushes, hard resets, rm -rf of broad paths, sudo, deploys, publishing, piping downloads into a shell, reading key/credential files, switching to main branches, …) and answers ask, which forces Claude Code's permission flow — and therefore your approval — whatever the autonomy level. Projects can add patterns. The self-improvement system never proposes pre-approving a command that matches these patterns.
SDK-managed workers get the same rules. An employee on the SDK runtime is given the same permission mode and allow/deny/ask rules through the Agent SDK's options; the bypass mode is never used there (an unrestricted employee on the SDK runtime runs as auto). A tool call that is not pre-approved goes to the office through the SDK's permission callback and is held exactly like a hook; if nobody answers in time it is asked in the worker's pane, where the default is no. The host's high-risk gate runs as an SDK PreToolUse callback and escalates the same commands. The runner authenticates to the host agent with that session's own token over the agent's private unix socket.
Workers do not inherit your MCP connectors by default (--strict-mcp-config): they get the Orchestrator server only. Turning on Settings → Employees → Employees also get your MCP servers and connectors gives every worker whatever those connectors can reach.
Changes that widen permissions are yours — unless you hand some of that over. Suggestions such as "pre-approve docker build" or "give Dana standard autonomy" are proposals; applying one is an owner action, recorded in the audit log, and takes effect for sessions started afterwards. What the office may apply by itself is set by one dial, the autopilot (settings.selfImprovement.autopilot; details and limits in learning/autopilot.md):
- off — nothing is applied without a person.
- safe (the default) — the office applies only changes that cannot let agents do more without asking: deny rules, required review, a longer verification timeout, a lower autonomy level, a lesson for one employee. (Text for a project's notes is suggested, never applied: every employee reads the notes as the project's own word.) It never adds an allow rule, raises autonomy or switches review off. "Safe" is about permissions only: a deny rule or a review gate applied this way can still get in the way of work until you undo it.
- trusted — the office also applies widening changes, each under a fixed evidence rule (for an allow rule: at least five approvals of exactly that command shape in that project, across two tasks or a day, not one denial ever, nothing of that shape on the high-risk list, never a shape that runs arbitrary other commands; for autonomy: one level at a time, never beyond standard, on a clean record), and each on probation: a denial, a high-risk request of that shape or a failure in that time takes it back, and it is not applied automatically again. On shared machines a colleague's approvals count as evidence like yours.
Whatever the dial says, the office never answers a permission request, never pre-approves anything that matches the high-risk list, never raises anybody's level (Auto and Unrestricted are a person's to give), and never changes the foreman. On a member's own computer it changes permissions only on that member's own decisions. Every automatic change is written to the audit log as autopilot, recorded as a learning.applied event with its evidence, and can be undone (POST /api/improvements/:id/revert, owners only). Like any rule change, an automatic one — and its undoing — reaches a session when that session is next started: a rule that is taken back stays in sessions already running until they restart.
The foreman is the office's supervisor: one Claude Code session, on one of the office's own machines, with the role foreman and no desk. It is a session like any other, so everything above applies to it. Only an owner can hire one or change who it is; hiring one switches its rounds on, and Settings → Foreman pauses them.
It supervises the whole office, members' own computers included. While a member's computer is connected, the foreman sees that member's employees the way an owner does: look_at shows it the last lines of their real terminal, and it can answer their questions, tell them what to do next and give them tasks of projects on that same computer. Until this change only the member and the owners could look into a personal employee. A member who brings their computer into an office that has a foreman is therefore supervised by it; what it reads becomes part of its conversation with Claude on the office's account. Because of that, the foreman itself is the owners' alone: colleagues and visitors cannot watch or type into its terminal, read its documents or session history, talk to it, start or stop it, or change its profile (access.ts: OWNERS_ONLY). They still see that it exists, where it walks and what it is doing.
Records: messages and questions follow the same rule as terminals — what is sent to the foreman, and its questions, are for owners; what the foreman tells an employee is read by whoever may read that employee. Of the foreman's own feed lines everyone receives only the outline (that a round started or ended and how many items of each kind, and whom it is with: FOREMAN_PUBLIC in access.ts); the items of a round — which quote questions, also of members' own employees — and its conclusion are sent to owners only.
What it may do, through tools only a foreman's session can call (the server checks the caller's role on every call; the caller is identified by the session's bearer token, never by an argument):
- read the office: every employee's role, activity, task and open question, every project's board, and — with
look_at— the last 40 lines of an employee's terminal screen; - answer an employee's question on your behalf, if the foreman answers employees' questions is on;
- assign tasks, create tasks, and tell an employee what to do next (
tell_employee: an ordinary message under its name) — never across the line between the shared office and a member's own computer; - put something in your inbox (
escalate_to_owner).
What it may not do, by construction rather than by instruction:
- Decide a permission request.
answer_questionrefuses every request that is not an ordinary question — permission requests, trust prompts, and questions an employee addressed to you as a decision, priority or deployment — and the engine's own answer path refuses a non-owner decision as well. Approvals stay with you and with each employee's autonomy level and the high-risk gate, exactly as before; no permission-bypass flag is used anywhere. - Touch a terminal or a session. It has no tool that types into, interrupts, starts, stops or takes control of anybody's session;
look_atonly reads the screen the host already captures for the office's monitors. - Edit files. The role denies Edit, Write, MultiEdit and NotebookEdit whatever autonomy level you give the foreman.
- Widen anyone's permissions, change settings or policies, release, review, merge or promote. Those have no foreman tool.
- Answer a question it escalated. Once it is in your inbox it is yours.
On the record. Everything a foreman does is written under foreman:<name>: answers (question.answer, with onBehalfOfOwner), assignments and created tasks (task history), escalations, and every refusal (foreman.refused; a non-foreman trying a foreman tool is foreman.tool_refused). An answered question records who answered it, and the employee is told it was the foreman. Rounds are events (foreman.round.started / .finished) with what was listed and what was done.
What to keep in mind.
- Terminal contents reach the foreman's model — also those of members' own employees. What
look_atreturns becomes part of the foreman's conversation with Claude, like anything a session reads. Values in known credential formats are redacted first; other sensitive text on a screen is not. Screen contents are not written to events or the audit log. - An employee's words reach the foreman's prompt. Questions, blocker reasons and task titles are quoted in the round digest, so a compromised or misled employee can try to steer the foreman. What that can achieve is bounded by the list above: tasks, assignments, messages and answers to questions — never an approval, a command or a file change.
- A wrong answer is still an answer. The foreman can answer a question you would have answered differently. The answer is on the record with its author; turn off the foreman answers employees' questions if you want every question yourself.
- Each round uses Claude usage on the account the foreman runs on. The office starts a round only for something new, never while one is running, and never sooner than the gap you set.
- Each employee works in its own git worktree on its own branch. Orchestrator refuses to switch branches over uncommitted work.
- Two employees are never given code tasks in the same plain (non-git) directory.
- When an employee works in place in your own folder, whatever was already uncommitted there when the task started is recorded as yours: it never blocks the task, the employee is told not to commit, change or delete it, and completion only looks at what changed during the task.
- Merges happen in a separate integration worktree,
--no-ff, intoorchestrator/integration. A conflicting merge is aborted and reported. Your checkout and yourmainare never modified. - Orchestrator never pushes, and
git pushis on the high-risk list.
When the desktop app connects to an office on another machine, it only accepts an https:// address (plain http:// is allowed for this computer alone), checks the owner token against the server before saving anything, and stores the token in its own data folder encrypted with the operating system's keychain facility when one is available (otherwise in a file readable only by you). On macOS this creates a login-keychain item named "Orchestrator Safe Storage"; because the app is not Developer-ID signed, macOS asks for your keychain password again after each rebuild. Set ORCH_NO_KEYCHAIN=1 to keep the token in the owner-only file instead. The connect page is a local file with a content-security policy that allows no remote content, and it can ask the main process for exactly one thing: to try a connection.
The page in the app's window is the office's: it is served by a machine that is somebody else's. The rules at that line are in apps/desktop/electron/guards.cjs (tested in apps/desktop/test/guards.test.ts) and wired in main.cjs:
- Navigation only within the office's origin, redirects included (
staysInOffice); outside links onlyhttp,https,mailto(externalUrl). - Permissions: the office's own page, and only microphone, clipboard, pointer lock, full screen and the choice of loudspeaker (
pageMay); the camera, screen capture, location, notifications and the rest are refused. - The TV (an embedded browser the page controls) has a storage per office (
tvPartition); another office's page cannot attach to it. - The credential reaches the page through
orch:boot, answered only for the window's top frame while it shows the office; it is not on any command line. The token that enrols the computer is passed in the environment. - Bringing a server in over SSH: the app's dialog shows the destination, port and folders it will really use and asks about trusting an unknown host key itself.
Not closed, and the owner's to decide (2026-11-11):
- A member's computer joins an office by itself. When somebody is let in as a colleague or an owner, the app enrols this computer as their own machine in that office without asking, with the whole home folder as where the office may work and with verification commands allowed — which is a shell on that computer for whoever runs the office. That is how the office is meant to work between people who trust each other (and how the owner's own Mac is in it); a stranger's office is another matter. A question on first joining an office, with the folders chosen there, would close it, at the price of one more step for every member.
- The relay's port while the app is closed. A member's sessions go on in tmux and keep calling
127.0.0.1:<port>; with the app closed nothing listens there, and another user of the same computer could. Not relevant on a computer with one user.
Who may do what is specified in ACCESS.md and enforced in apps/server/src/access.ts; a route that is not listed there needs an owner.
- Credentials. A member's credential is a random token (stored hashed), bound to a name and a role, revocable, replaceable. It is not what the owner sends: the owner sends an invitation link whose code the member's app exchanges for the credential once, at the door, within a week (
apps/server/src/invites.ts; the code is stored hashed, twelve characters from an alphabet of 31, and wrong codes are limited to ten per address per ten minutes). A link that leaks after it was used opens nothing; one that leaks before lets whoever is first come in as that member — so it is still sent privately, and Access shows whether it is still waiting to be used. In an office with no address set, the invitation is the old long text, which carries the credential itself. The server's own owner token is a different kind of credential and is refused on any request that came through the door, so it cannot be used from the network even if it leaks. - The door. A second listener with TLS and a self-signed certificate made on the server; a link to the door's own address carries the first ten bytes of its SHA-256 fingerprint and the app exchanges the code only with that certificate; what it gets back names the whole fingerprint, and from then on the app accepts exactly that certificate (and sends the token only after checking it). Behind a reverse proxy the app checks the proxy's certificate as a browser would. It forwards the page,
/api, the client WebSocket, the agent WebSocket,/mcp, and the two things that need no credential —/knockand/join; nothing else. Requests through it are marked with a per-process secret header that the door overwrites, so a caller cannot forge or strip the mark. - Machines from outside. Through the door the agent endpoint accepts only a member's own computer: a host enrolled with a one-time token that
POST /api/me/hostgave to that member (10 minutes, single use), or the credential such a host was issued. An ordinary enrollment token or a shared machine's credential is refused there. Revoking a member, or making them a visitor, revokes their hosts. - A personal host on Windows runs inside the member's WSL2 distribution (
wsl-host.cjs). The member's token reaches it on the standard input of the process the app starts, never on a command line. Its allowed roots are the WSL home, the member's Windows profile folder (/mnt/c/Users/<name>) and the folders the member names inORCH_PERSONAL_ROOTS; other Windows drives are not opened. As everywhere, owners can reach what those roots hold. - A member's own servers (
apps/desktop/electron/member-servers.cjs). The desktop app reaches the server with the system'sssh, as the person: BatchMode (their keys and agent, never a password), host keys checked the normal way, an unknown one accepted only when they tick that they trust the server. Because a page — which is the office's — is what asks, the app confirms adding and removing a server in a dialog of its own that names the server and the office. On the server it writes only under~/.orchestrator(the agent, a launcher, a folder for this office) and starts the agent; the enrolment token is on no command line. Changing the folders later (Folders…) is confirmed in the same kind of dialog, since it widens what the office may work in there. Browse the server… lets the member pick those folders from a list: the app reads the names of folders over SSH — whatever the server's user can open, not only what is already allowed — and hands them to the page, which is the office's; so the app asks first, once per server until it is closed, and it reads names of folders only (no files, nothing hidden). Looking allows nothing: the agent on the server keeps to the list it was last started with. The agent then connects to the office's address with ordinary certificate checking, which is why an office without a publicly trusted certificate is refused. What the office can do on that server is what it can do on any machine: start sessions in the folders the member named, as that user. Bringing a server in gives the office that much of it — and, once shared, gives it to every colleague. - A closed room. A member who closes their room keeps the owners of the office and the foreman out of what is on their own computers (
ACCESS.md). This is enforced by the office's interface, for the people who use it; whoever has a shell on the office's machine can still read its database, and whoever runs the office can still start a session on a connected machine by other means. It is privacy among colleagues, not a defence against the office's operator. A member who needs that should not bring the machine in. - What a personal host exposes. To the office: what any host agent exposes (terminals of sessions the office started there, folders under the agent's allowed roots, the list of Claude processes) — but only its member and owners can reach any of it, including monitor frames, which are filtered per client. A member who does not want owners to be able to open a terminal on their computer should not join as a colleague with that computer.
- An office behind a domain. A reverse proxy must forward to the door, not to the office's own port: loopback requests to the office itself are treated as local (they may present the owner token and enrol shared machines). For such an address the desktop app relies on ordinary web trust (a certificate valid for the name) instead of the pinned fingerprint; whoever controls the domain or the proxy in front of it (here: Cloudflare and the server's nginx) can see and alter the traffic, as with any website behind them.
- The relay's port is remembered (
relay-portin the office's folder on that computer, mode 600) so that it comes back on the same one; it listens on loopback only, as before, and forwards the same two things. - The relay. The agent and Claude Code on a member's computer speak plain HTTP to a relay on that computer's loopback, which connects to the office with the pinned certificate and forwards only
/ws/agent,/mcpand/healthz. It holds no credentials. - A showcase office lets anybody in (
ServerOptions.showcase, only the public demo —docs/DEMO.md): every knock at its door is admitted at once, as an owner, for twelve hours. What it may change through the door is a fixed list of the office's work (SHOWCASE_WORK): nothing that runs the office (settings, access, vault, accounts, machines, floor plan, uploads) and no delete; voices are not passed on. It is a separate server with its own database and token. Its employees are the scripted stand-in, which carries out scripts written into what it is told — so in the demo it runs only scripts signed with a key of that start's own (ORCH_FAKE_KEY), the director's; anybody else's words get harmless stand-in work (checked intests/e2e/58-showcase.test.ts). Never switchshowcaseon for an office with real employees, and never run the stand-in for strangers without its key. - Visitors can watch shared terminals (the owners' word again on 2026-11-12, when everything else a visitor was sent was cut down —
docs/ACCESS.md, "What a visitor is sent"). Terminal output can contain secrets that the redactor (which works on events, not on raw terminal streams) does not remove, and Claude Code's own screen can show the model, the account and folders. Invite visitors accordingly. - Files said to an employee (
docs/ATTACHMENTS.md, "Files in a conversation") follow the rules of a task's files: bytes in the office's data folder under ids, a name that is only a name, written on the machine by its agent into its own folder outside every repository (mode 600), shown back only as PNG, JPEG, GIF or WebP and otherwise as a download withnosniff. Sending and seeing them is for whoever may talk to that employee; a file belongs to whoever uploaded it until it is said. The office drops its copy after seven days; the copy on the employee's machine stays until somebody removes it there. - A member's team lead can hire. It is the one employee whose session can add employees by itself, so what it can do with that is fixed on the server, not left to its prompt: onto its own member's machines only, a role from the catalogue (not foreman, not lead), the role's own autonomy (never Unrestricted), a project of the team's or a folder the machine already lets the office into, and at most five people hired by it at a time; each hire is in the audit log (
lead.hired) and told to the member. A message from outside that steers a lead's session can at worst make it hire up to that limit, or hand a request to one of the member's own employees. Its session cannot edit files.docs/TEAM-LEAD.md. - What a visitor is sent is cut on the server (since 2026-11-12). Until then a visitor's browser received the whole state of the office — every employee's model, instructions and folders, every session's paths and cost, the machines' host names and users, projects' repository paths and rules, tasks in full (members' own included), and all notifications, among them members' employees' questions and sign-in alerts with addresses — and the page merely did not show most of it. Now
shownToleaves it out of the state and of every live message, and the routes behind those things (documents, diffs, attachments, accounts, routines, performance, the growth record) refuse a visitor. - Colleagues can type into shared terminals and decide permission requests of shared employees. A colleague therefore has, in effect, shell access as the office's user on shared machines, within what Claude Code's permission rules allow. Give that role to people you would give an account on the server.
- Audit. Every change a member makes is recorded as
member:<name>with the route; answers and decisions record who gave them.
message_person (MESSAGE-PERSON.md) puts what an employee wrote in front of a person — their Inbox and, through the employee's own bot, their Telegram. So: only owners and colleagues who are in now can be written to (no visitors, nobody revoked); an employee on a member's own computer writes to that member only; twenty in an hour at most; the notification is addressed (Notification.for) and filtered out of everybody else's state, live updates and read/dismiss actions; the feed records who wrote to whom, not what. What is written is the employee's words — a steered employee can still write misleading text to a person, as it can in any message.
Where the office keeps passwords, tokens and keys (packages/orchestration/src/vault.ts, vault-detect.ts).
- At rest. Each value is encrypted with AES-256-GCM under a 32-byte key and stored in the office's database with the entry's id as authenticated data; a keyed hash of the value (HMAC-SHA-256) lets the same value be recognised without being readable. The key is
vault.keynext to the database (~/.orchestrator-office/server/, mode 600), made on first use, orORCH_VAULT_KEY(base64) from the environment. Whoever can read that folder can read the vault — the same as the office's own owner token, which lives there too. Back the key up with the database: without it nothing in the vault can be read, and the office says so rather than returning rubbish. - What never carries a value: the list (
GET /api/vault), the office state sent to windows, events, the audit log, notifications, messages and tasks (they carry{{vault:name}}). A value leaves the server in two ways only: to an owner who asks to see one (reveal: recorded,cache-control: no-store), and to a command in an employee's session. - How an employee uses one. Every session has a helper in its own folder (
$ORCH_VAULT, written at launch beside the session'smcp.json, private to the user the agent runs as). A command writes$("$ORCH_VAULT" get name)where it needs the value; the helper asks the office with the session's own token, the office records the use, and the value goes into the command — not into the model's conversation, unless the command prints it. That last part is not enforced: a command canechoa credential, and then it is on the terminal (which visitors may watch) and in the model's context. The employee's instructions forbid it; nothing stops it. - A new value under the same name (
PUT /api/vault/:id/value, owners only): the entry is encrypted again with the new value and its keyed hash replaced; the old value is not kept anywhere in the vault. Recorded asvault.changed(who, which name — never the value). Refused when the new value is already in the vault under another name. - What is moved in by itself. A credential written into a message to an employee, a task or an answer is taken out before it is stored or delivered: provider token formats, private keys, passwords inside addresses,
PASSWORD=…-style fields, and sentences like "the password for X is …" when the value has the shape of a password (letters, digits and a capital or a symbol, eight or more). Code is left alone (process.env.API_KEY,$TOKEN,<your-token>). Anything that needs judgement is not caught here — the employee who reads it is told to store what is plainly a credential. A key in an unmistakable format that goes through a session (a prompt, a command, what a tool returned) is kept too, and the owner is told where. - Limits, plainly. No per-credential permissions and no per-project vaults: every employee can use everything. An employee on a member's own computer can take values there. A credential that was already delivered or printed before it reached the vault is still wherever it went. Removing an entry deletes it here; it keeps working wherever it is used until it is changed there. SDK-managed workers have the tools but not the helper. Not verified with real Claude Code: that it uses the helper rather than asking for values, and what its permission prompt shows for a command with
$("$ORCH_VAULT" get …).
With Employees manage the task board themselves on (the default), an employee's session can release, unblock, assign and review tasks and start a colleague's session (docs/CLAUDE-CODE-INTEGRATION.md, "The board in the employees' hands"). What that changes for safety:
- More work can start without the owner. A released task is handed to an employee, who then acts with that employee's own autonomy level and permission rules — those are unchanged, and high-risk commands still come to the owner where the office is set to ask. Starting a colleague uses that colleague's Claude account.
- A review by a teammate lets a change be merged into the project's integration branch. The author cannot approve their own work; promotion to the base branch stays an owner's action.
- Text an employee read can steer these tools like any other tool it has (a web page or a file saying "release every task"). The tools cannot approve a permission request, delete anything, change policy, or reach across the line between the shared office and a member's own computer, and each use is on the record under the employee's name. Switch the setting off for an office where that is not enough.
- The only thing an unauthenticated caller can do at the door besides fetching the page: leave a name (plain text, 40 characters) and wait. They learn the office's name, a four-digit code, and whether anyone who could answer is inside. They learn nothing else and get no credential until a person inside lets them in.
- Letting someone in is a decision by a signed-in owner or colleague, recorded in the audit log (
knock.admitted/knock.refused, with who answered). A colleague cannot grant more than a read-only visit; only an owner can let someone in to work. A browser is never more than a visitor, and for 12 hours. - Anyone can type any name. The card inside says how the person came and shows the code they see; the owner is told to ask for the code if they are not expecting the person. Letting a stranger in as owner gives them the office — the same as handing them an owner invitation.
- The knocker proves they are the same caller with a random secret (32 bytes; only its hash is kept), sent in a header, never in the address. The credential is returned once; if it is never collected the member is revoked.
- Flooding: per-address and total limits (see ACCESS.md). The address is the socket's; behind the reverse proxy on the same machine it is the last entry of
X-Forwarded-For(what that proxy saw). A proxy that forwards the header without appending would let a caller pick their own "address" for the limit — the total limit of 10 waiting still holds. - The desktop app knocks only at an address whose certificate the computer trusts for that name; an office with only its own certificate is not asked by address (there would be nothing to check it against) and still needs an invitation.
The TV is an Electron <webview>, and the only one the office window may create (will-attach-webview refuses any other partition and any non-http(s) address). It runs sandboxed with no Node integration and no preload, in its own storage partition (persist:orch-tv), under a plain browser user agent. Requests from it to the office's own address are cancelled, so a web page cannot talk to your office; file: and other schemes are refused; pop-ups open in the TV itself; camera, microphone, location and notifications are denied (only fullscreen is allowed). About once a second the main process takes a small picture of the page for the screen in the 3D office; it is not stored. "Forget browsing data" clears the partition. In a plain browser tab (no desktop app) the TV can only embed YouTube video.
The arcade runs a third-party emulator (RetroArch with Genesis Plus GX, as WebAssembly) on cartridge files a person brings. docs/ARCADE.md, "The frame".
- It is not on the office's page. It runs in
<iframe sandbox="allow-scripts">at/assets/arcade.html: a page with no origin, which cannot read the office's storage or credential, and whose own policy (default-src 'none', scripts from the app's files, blob and WebAssembly only,connect-src blob: data:) gives it no network. The office's page keepsscript-src 'self'; it gainedframe-src 'self'. - The frame is handed bytes and hands bytes back (
postMessage; each side checks that the message came from the other's window). It never has the keyboard. - What changed on the server for it:
X-Frame-OptionsisSAMEORIGINfor exactly/assets/arcade.htmlandDENYfor everything else, as before; files under/assets/(the app's built files, which the door hands to anybody) carryAccess-Control-Allow-Origin: *, because a script module is only given to a page with no origin when the file allows it. Nothing under/apihas that header. The door's list of paths is unchanged. e2e49-arcade-frame. - Cartridges are kept with the office (
<data folder>/arcade/, since the afternoon of 2026-11-12) and handed to everyone who is in — visitors too — and to nobody without a credential; bringing and removing is for those who work here; who did is in the audit log. A cartridge arrives in pieces, is at most 16 MB, must have a cartridge's file extension, and is named by the SHA-1 the office works out itself. It is served as a download (nosniff,attachment), never as a page. Saves stay in the player's browser. - A game played together goes through the office as messages (
arcade.*,apps/server/src/arcade.ts): the host's picture and sound to those at its table, the second pad's buttons to the host. The office decides who is host (the window that opened the table), who holds pad 2 (the first who asked) and passes on nothing from anybody else; it keeps nothing of a game. Limits: 700 KB a piece, 240 pieces a second a host, ten people a table. What arrives at a guest is decoded by the browser's own video and audio decoders and drawn on a canvas; nothing of it is run. e2e50-arcade-shared. - Not protected against: a cartridge file that makes the emulator misbehave can do so only inside the frame (it can waste the processor, show anything on the cabinet's screen, and hand back nonsense as a "save", which is stored as bytes and only ever given back to the same emulator).
An SSH link runs the system ssh client as you, with BatchMode=yes: only your keys and agent are used, a password is never asked for, read or stored. Host keys are checked the normal way; an unknown key is refused unless you explicitly trust that server for the first connection (StrictHostKeyChecking=accept-new: the key is then pinned in your known_hosts, and a changed key is refused with a warning). What you type as the server is validated (user@host[:port] or a config alias) and passed as an argument, never through a shell; scripts run on the server are fixed text sent on standard input, with the few values that vary single-quoted.
The reverse tunnel puts the office's port on the server's loopback interface only. Any local user or process on that server can therefore reach the office's HTTP port there — and gets nothing without a credential: the owner API needs the owner token (which never leaves your computer), the agent endpoint needs the host credential, and the MCP endpoint needs a per-session token. On a server shared with people you do not trust, prefer a dedicated account. The agent enrols with a single-use, ten-minute token passed in the environment (not on a command line), and stores its credential in ~/.orchestrator/links/<id>/config.json, mode 600. Removing the link stops the agent, deletes that folder and revokes the credential; revoking the machine under Machines has the same effect on access.
The host's allowedRoots (your home folder on the server unless you list others) bound where employees can be started and what the office can read there. Turning an attached session into a full employee types /exit into Claude Code — sessions the office did not start are never killed.
The office can list the Markdown files in an employee's folder and show them, and can list folders on a machine so you can choose one when hiring. Both are read-only, go through the host agent, and stay inside that host's allowedRoots: only .md/.markdown/.mdx files are ever read, paths are resolved and must remain inside the employee's folder (a symbolic link that points elsewhere is not followed), files are capped at 512 KB, and hidden folders and dependency folders are skipped. What agents write is shown as formatted Markdown by a renderer that builds elements directly — no HTML from an agent is ever inserted into the page, and only http(s)/mailto links are clickable.
The one thing the office can make there is an empty folder (fs.mkdir, from "New folder" when a folder is chosen for an employee): one level, inside the same allowed roots, with a name that is one visible name — no path, no leading dot or dash, no control characters — and never over something that exists. Whoever may put employees on that machine may do it (an owner or a colleague on a shared machine; on a member's own computer, that member); it is in the audit log as folder.created.
The office page may play audio from any http(s) address (media-src in its content policy) and nothing else from outside: scripts, styles, images and network calls stay limited to the office itself. Stations are saved in the settings (an owner's act), and only well-formed http(s) addresses with a name are kept. The hi-fi plays for the whole office: when an owner or a colleague switches a station on, every window in the office loads that station's stream itself. A request to play names a saved station by its id — an address that is not on the office's list is refused, and a visitor cannot switch at all — so no member below owner can make other people's windows load an address of their choosing. No audio passes through the office server. "What is on air" is asked by the office server, for saved stations only, with a five-second limit and a size limit; only a title of at most 200 characters is passed on to the page. Playing a station tells that station's server the IP address of everyone in the office who has not muted the hi-fi (a muted window does not load the stream), as any radio player does.
Push-to-talk sends the microphone's sound to the office only while the talk key is held (the browser or the operating system asks for the microphone the first time; the desktop app's TV keeps being refused it). A person may instead keep their microphone always on (Settings → Sound; off unless they choose it, on that computer only): then what is louder than their own mark is sent without a key, also while the window is not in front; the talk key switches the microphone off, and the window shows the whole time whether it is on. The office treats those frames exactly like the others. Frames go over the member's authenticated WebSocket; the office checks each one (size, alphabet, at most 45 a second per window), and passes it only to windows whose character is in earshot — in range and on the same side of a closed meeting room's walls — so a window cannot hear a meeting by ignoring a rule in the page. Nothing is recorded or logged; a frame is forgotten once passed on. The sound is not end-to-end encrypted: it is protected by TLS to the office like everything else, and whoever runs the office's server could listen. A person in the same closed meeting room hears everything said in it, visitors included: who is in the room is visible. Gestures and the whip between people carry a name from a fixed list and a person's id, nothing free-form. With The whip approves switched on (off by default), a crack answers allow on the employee's open permission questions — only those the whipper is allowed to answer, checked by the same rule as the button, and recorded in the audit log as their answer. It widens nobody's rights; it does make approving something one did not read a single key press, which is why it is a setting the owner turns on.
An employee on Auto is governed by Claude Code's own safety check. When it refuses an action, the office asks the owner (an approval request; the foreman and employees can never decide it). On Allow:
- the employee's machine lets one call through that is identical to the refused one — a shell command by its exact text, any other tool by its whole input — within ten minutes; the grant is used up by that call and covers nothing else;
- the employee is told so in a message from the owner.
Deny rules of the project still win (Claude Code evaluates them whatever a hook says). The decision is audited (
approval.decide,approval.granted_once). What is shown to the owner is the command as Claude Code reported it and the reason it gave. This is the same act as approving an ordinary permission request — it does not widen what the session may do afterwards.
apps/server/src/logins.ts; POST /login at the door. A member who has a password can sign in at the office's address with their name; what they get is a credential of that member with that member's role, valid for 30 days, kept by the browser like any member credential.
- What is stored: per member a random 16-byte salt and a 64-byte scrypt hash (N 16384, r 8, p 1; the password NFKC-normalised first), in the office's store under
logins, apart from the member records that are sent to windows. A password is never written to a log, an audit entry, a notification or an answer; the Access list says only has one. - What an attempt is told: "That name and password do not match a member of this office" — the same for an unknown name, a member with no password, one who was removed or whose time is up, and a wrong password; the hash is computed in every case so the answer takes the same time.
- What slows guessing: five wrong passwords in a row close the name (for the right password too) for 15 minutes, then 30, and so on up to a day; the owners get a security notification and the audit log an entry (
login.locked). Twenty wrong attempts from one address within ten minutes close that address (429). The address is the one the door reports (the peer, or what a proxy on the same machine says) — not a header a caller sends. A flood from many addresses is turned away as a whole: at most eight checks are computed at once and 120 attempts a minute are taken from everybody together (429 beyond either), and a check is computed on a worker thread, so guessing cannot stall the office. These counters are in memory and a restart clears them. - What ends a session: Sign out (that one session), a changed or removed password (every session made with it), a new invitation for the member, removing the member. Ending a session also closes the live connections that were opened with it (
ClientHub.dropLogins; the connection remembers a hash of its token, not the token) — until 2026-11-11 16:55 UTC an open page stayed connected until it was reloaded. The desktop app's own credential is ended only by the last two. - A new invitation removes the password (since 2026-11-11, 17:15 UTC): a member can set a first password with nothing but their credential, so whoever held a leaked credential could have set one; re-inviting the member closes that way in with the rest.
- Who sets a password: an owner for anybody (
POST/DELETE /api/guests/:id/password), a member for themselves knowing the current one (POST /api/me/password, counted like a sign-in attempt), and whoever has a shell on the server (office-admin password, read from standard input — not from the command line, which other users of the machine can see). - What it does not change: the office's own owner token is not accepted through the door; an owner who signs in is a member with the role owner. A phone is turned away before the password is looked at. There is no second factor: for an owner, the password is as strong a key as their invitation was — choose it accordingly, and note that somebody who knows a member's name can keep that name's password sign-in closed by guessing wrongly (the app and invitations still work).
- Audit:
login.password_set,login.password_removed,login.signed_in(with the address),login.failed(the name tried, cut to 40 characters, and the address),login.locked.
Clients of the office talk to the employees they rent at <address>/rent (docs/RENT.md).
- A client is not a member. Their sessions are credentials of a kind of their own (
client) that nothing but/rent/apitakes: the owner API, the office's WebSocket and the worker endpoint answer them 401. There they reach only the employees they rent (404 for any other), and only the files of their own conversations. - Links and passwords work as the members' do, kept apart: a link's code is stored as a hash, works once, for a week, is rate-limited per address, and is used up only once a password was set with it; passwords are scrypt hashes with the same locks on guessing; a new link takes the password and every session away; ending the rental ends everything.
- What is said with clients is the owners': not sent to colleagues or visitors; the feed says only that a client wrote.
- Two switches reach further, and are off by default: Anywhere takes the folder fence away (the whole machine and servers; the office's own files stay fenced), Never waits lets what the other switches allow run without the owner's approval, the high-risk hold included — the owner's per-employee choice, audited as
rent.allowed_unasked(DECISIONS.md, 2026-11-16). - A rented employee is walled and fenced: they reach only the employees of the same client (
reaches), are given only a fixed set of the office's tools (no vault, no memory unless the owner allows; no board, lessons, hiring), and on their machine every tool call is checked against their folders and the owner's switches (rentFence) — changed live. The command check reads the paths a command writes out; it is not a sandbox (RENT.md, "Limits"). The office's own-files fence and the high-risk gate stay in front of it as for everyone.
An employee's bot (docs/TELEGRAM.md) is a way to talk to them, not a terminal: what comes in is delivered as a message from the person, through the same delivery, deny rules, high-risk gate and permission prompts as Talk.
- The token is sealed with the vault key (AES-256-GCM, kv
telegram.bots), sent once from the window and never returned to a window, an event, an error (Telegram's errors are redacted) or a log. - Who is served: only people who paired with a one-time code (random, kept as a SHA-256 hash, ten minutes, made by somebody with work on that employee), and groups connected with such a code. Anybody else is told the bot is private; an unconnected group is left. A paired person or a group speaks as the member who made the code, and that member's rights are checked again on every message — losing access to the employee ends the chat. A button on a permission request decides as the person who pressed it, only if paired; questions and permissions never go to a group.
- No open port: the office polls Telegram (
getUpdates); no webhook. - The public demo refuses every Telegram route.
A phone's browser is refused at the server (phone.ts): a page that says the office is for a computer, or a 403 for everything that is not a page. It is recognised by its User-Agent, so it is not a security boundary — it keeps people from entering something that does not work on a phone, nothing more. Access is decided by invitations, tokens and roles as before.
When the office could not hold a request for approval (nobody answered in time, or the office restarted), Claude Code shows its own prompt in the session's terminal. The office reads the session's screen, asks the same question again as an approval request, and — only when a person who may decide it answers — presses the keys for that answer in the terminal.
- A restart of the office is not such a case any more when the machine's agent stays up: the agent holds the request (up to 90 s) and the office takes the same question up again — nothing is decided by the restart, and an answer is delivered only to the request it was given for (matched by the hook event's id, from the same machine). A question (not a permission) that ends up in the terminal is only announced to the owner; the office does not press keys at it.
- Who decides is unchanged: owners and whoever may work with that employee; never an employee, never the foreman, never the office by itself. Nothing is approved because it waited long.
- What is pressed: the keys that move to the plain Yes (or to No) among the options the prompt shows at that moment, and Enter. "Yes, and don't ask again" is never chosen. If the prompt is no longer the last thing on the screen, nothing is pressed and the answer is reported as not delivered.
- What the request shows is what the dialog shows (the command or file, and the reason the hook gave), taken from the screen; it is as trustworthy as the terminal itself. A session cannot make the office approve anything by printing text that looks like a dialog: a look-alike only produces a question for a person, and a person's "Allow" presses Enter in that session's own terminal.
(ATTACHMENTS.md explains the feature.) What a person attaches, and what an employee leaves as evidence, is kept in the office's data folder (files/, mode 700; each file 600) and sent only to those who may see the task — the same rule as the task itself, a member's closed room included.
- Nothing attached is ever served as a page. Only PNG, JPEG, GIF and WebP are sent as what they are; every other file — HTML, SVG, PDF — goes out as a download (
application/octet-stream,nosniff, a sandboxing content policy). The window fetches files with the person's own token; there is no address that shows a file to someone who is not signed in. - On an employee's machine an attached file is written by that machine's agent into its own folder (
<agent home>/files/<task>/, mode 600), under a name the office made safe and the agent checks again. It is never written into a repository or anywhere the office names. - Evidence is read by the machine's agent, not sent by the model.
attach_filemay name only a regular file inside the agent's allowed roots, the agent's own folders or the temp folder — and never the agent's or Claude Code's own configuration and credential files there. An employee can still attach a file it should not (a.envinside its project): its instructions forbid it, nothing prevents it, and what is attached is visible to everyone who may see the task. The vault does not look inside files. - Limits: 100 MB a file, 200 files a task; an upload that goes quiet for ten minutes is dropped.
An attachment can be opened by everybody who works here and sees its task (not by a visitor, since 2026-11-12), and the machine's agent reads the file itself — Claude Code's permission rules are not asked. So attach_file takes a file only from the employee's working folder, its browser's folder, the office's own files for it, or a temporary folder, and refuses hidden files and anything named like a key or a credential (getFile in apps/host-agent/src/agent.ts). Until 2026-11-11 it reached wherever the machine's allowed folders did — on the office's server the whole home folder, with ~/.ssh and the office's token, vault key and database in it. It was found by a review, not by an incident: every file employees had attached up to then — twenty, all recorded in the feed — is a PNG screenshot of their work, taken from Claude Code's scratch folder under /tmp (checked on the server on 2026-11-11, after the fix; that folder is still allowed).
Where Playwright's MCP server is installed on a machine and the office's switch is on (Settings → Employees; on by default), every session there has a headless browser of its own, as the same OS user, with a profile kept in memory for that session only.
- It can reach whatever the machine can reach — the internet, and addresses inside the machine's own network. It adds no access the session's shell (
curl) did not have; it makes that access easier to use. - A page can say anything, and what a page says can steer a model ("ignore your task and …"). Employees are told that text on a page is information, never an instruction; that is guidance, not a guarantee. The session's permission mode, the high-risk command list and "no agent decides a permission request" apply to whatever a steered model then tries. Switch the browser off for work that must not touch the web.
- Credentials: the browser starts with no logins. An employee is told not to type a credential into a page unless the task is about that site, and to take it from the vault; a value typed into a page is in that page's hands.
- The office never installs it. A person does, once per machine, at a pinned version (
ATTACHMENTS.md); the office only finds it. The browser tools are allowed without a prompt (mcp__browser), like the office's own.
To show how much of each Claude account is used, the host agent reads two fields (emailAddress, organizationName) from Claude Code's own .claude.json on that machine, and the rate-limit percentages Claude Code gives the session's status line. It reads no credentials and never calls Anthropic itself. The account e-mail and the percentages go to your office server only; the percentages are shown to owners and colleagues, the e-mail and organisation only to those who may work on that machine, and a visitor is refused GET /api/usage altogether. The e-mail is written into one event: account.switched, when an employee is moved to another account, names the account in its line for the feed — read by whoever may read that employee's events, colleagues included for a shared machine; a visitor gets events without their lines. (An earlier version of this page said the e-mail was in no event and that no guest could ask for the usage; neither was true.) An employee's own account folder must be inside the home folder of the user the agent runs as.
Several accounts on a machine (ACCOUNTS.md). Adding an account makes a folder (mode 700) in that user's home and a link inside it to the default account's conversations; it is an owner's act and the folder's name is limited to ~/<one name>. The office never logs in to an account and holds no Claude credential: a person runs claude in that folder on the machine and logs in there. Moving employees between accounts changes which folder their session starts in, nothing else. Because the accounts of one machine share one conversations folder, a session on one account can read the conversations of the others — they are the same office's employees under the same OS user, who could read those files anyway.
The agent operates only inside allowedRoots (symlinks resolved, so a link cannot escape a root). The default is the user's home directory — narrow it with --allow-root.
State directories are created 0700; the database, tokens, session settings and outbox are 0600.
- Event summaries and payloads are passed through a redactor (API keys, tokens, private keys,
NAME=secretassignments, JWTs) before they are stored. File contents written by agents are never stored in events. - The audit log records actor, action and target for approvals, control changes, session lifecycle, project/employee/policy changes and applied suggestions; details are redacted the same way.
- Credentials are stored as SHA-256 hashes; plaintext is shown once.
The office's own token opens everything on the machine it runs on (it is refused from the network). When the server starts it tells a person at a terminal the link that opens the office, token included; when its output is not a terminal (a service's journal, a file) it prints only the address and the path of the token file (startupLines in apps/server/src/main.ts). Until 2026-11-11 the link went into the journal at every start. There is no command that replaces the token; to replace it by hand, stop the office, delete owner-token in its data folder and the owner credential with it — not done, and not needed unless the journal was read by somebody who should not have.
A task's branch lives in its author's folder until the work is merged. TaskEvidence.headSha is the commit the branch stood at when the work was handed in and verified; git.merge is asked for that commit (mergeBranch, sha), refuses one that is no longer on the branch, and reports how many later commits it left out. An approved review is cleared when the task is handed to its author again. The one exception is a person's own Retry merge on a blocked task: that merges the branch as it stands (it is how a conflict resolved by hand in the author's folder gets in), and is recorded as such. Approved work whose machine cannot be reached is BLOCKED ("Waiting to be merged into…") and is merged when the machine reports in (TaskManager.mergeWaiting). On a member's computer with an older agent the commit is not passed on yet and the branch is merged as before.
A session can be steered by what it reads. What its tools then cannot do (checked in tests/e2e/41-tools-and-lines.test.ts):
- carry work across the line between the shared office and a member's own computer —
TaskManager.mayTakeis asked wherever somebody is given a task, andstartTaskasks once more; - approve its own work —
Task.authorIdis whoever handed the work in; a task in review is not given away by an employee; - type keys into a colleague's terminal —
pasteable(packages/execution/src/tmux.ts) strips control characters from everything pasted; - reach into a closed room — messages, requests and the foreman's tasks are refused there;
- act as the foreman or use it — it reviews, releases and unblocks nothing, takes no tasks and reviews;
- open the office's own files on its machine —
HostAgent.officeFiles: file tools are refused, commands that name them go to the owner. This is not isolation: all sessions of a machine run as one user, and a path the command builds itself is not seen. An office that must hold against its own employees needs the foreman (and the office's data) under another user; that is not built. - fill the office — hourly ceilings per employee (
tooManyinmcp-tools.ts).
Talking across the line (a message to an employee on a member's own computer whose room is open) is allowed and stays so; get_team says it.
Text reaches the office from people and programs that do not run it: what an employee's session says (and a session can be steered by what it reads), what a stranger types at the door, what a request's headers claim. Checked in tests/e2e/43-untrusted-text.test.ts and the unit tests named below.
- An approval covers exactly what was shown. The tool's input is kept whole up to 200,000 characters per field and shown whole in the request's window; beyond that the rest is counted (
Question.tool.notShown) andCommunicationHub.answerrefuses allow — such a request can only be refused, or decided at the terminal. (HookReceiver.toolShown.) - Reading text takes time in step with its length. The office and each machine's agent have one thread; a pattern that takes time with the square of the text's length lets one long text stop everything else. The patterns of the vault's detector (
vault-detect.ts; timed inpackages/orchestration/test/vault.test.ts), the default high-risk list (prompts.ts;high-risk.test.ts) and the fence's reading of a command (HostAgent.officeFiles: a budget of look-ups, plain paths first;apps/host-agent/test/office-files-fence.test.ts) are written and tested for that. An eighth review then went through the rest (hooks' reading of a command, lessons, questions, the command bar, the terminal-screen readers, paths in task text, a check's output, the memory's reply —packages/orchestration/test/slow-text.test.tstimes them;stripEndinpackages/contracts/src/util.tsis how an end is trimmed). A project's own high-risk patterns are run as written, on every command of its employees: they are the owners' to set (access.ts; a member's on their own computer), must compile, and there are at most a hundred — a pattern that never finishes is still possible for whoever may set them. Not gone through:learning/outcomes.ts,waits.ts,sleep.ts, parts of the detectors and ofregistry.ts,packages/game-systems,postgres.ts; and what is only linear but heavy (an 8 MB hook payload is redacted several times over). - The page draws text as text. Markdown is built as React elements (no HTML is injected), links are
http(s)/mailtoonly, and a line over 4,000 characters is shown as written. A part of the page that fails to draw is replaced by a notice (Boundaryinapps/desktop/src/hud/boundary.tsx: the whole page, and each window), so one bad record does not blank the office; and the office refuses a change to a project or a task whose fields are not the kinds they must be (shapedintasks.ts). Other records are not validated this way. - A credential in the address (
?token=) is adopted only by a browser that holds none, or on a loopback address (adoptUrlToken); it is always removed from the address bar. - Lengths. A task, a project and an employee have a longest length per field at creation and at every change (
shaped,within,EMPLOYEE_SIZES); a question is cut to 4,000 characters however it was asked; an instruction at the command bar and a recorded lesson to 4,000. A machine's screen frame is taken only as lines of text of a screen's size. - What a shared project lets its employees run (
policy.allow,policy.deny,policy.highRiskPatterns) changes only at an owner's hand; a colleague's save of the project window with those three unchanged goes through (mayCall). - Names at the door are normalised (NFKC), stripped of invisible characters, and — for somebody who knocks — never the owner's, "Owner"/"Boss"/"Orchestrator", or an employee's (
Guests.answeredTo); an owner's own invitation may name anybody. Look-alike letters of other alphabets are not folded: the code on the card is still what tells a person from a pretender. - The office does not fetch for anybody. The one address the server fetches on a person's say-so ("now playing" of a saved station — saving one is an owner's act) is refused when it is, or resolves to, this machine or a private network while the door is open, and redirects are followed by hand with the same check (
radio.ts). The name is resolved once for the check and again by the request: a name that changes its answer in between is not caught. - The installer script (
/install-agent.sh, not behind the door) carries the office's address only when it is a plain web address (safeServerUrl).
Six reviews by a second reader, each given code and no conclusions, found some sixty defects in two days' work; none was known to have been used. The ones that were holes in what this page promises, now closed: a websocket frame that stopped the office (unauthenticated, through the door); a member's computer taking over a shared employee or the foreman by name; a session's tools token outliving its machine's place in the office; attach_file reading the whole home folder; a held high-risk command running when the agent restarted; a removed member's shared server and unused enrollment staying valid; an owner reaching into a closed room through a percent-encoded path; a credential from a member's own computer landing in the office's vault. Each is described where its subject is (above, HELD-REQUESTS.md, SIGN-IN.md, ATTACHMENTS.md, VAULT.md) and in CHANGELOG.md. Not changed, and still as written: a knock says itself whether it comes from the app or a browser (so the 12-hour visitor limit for browser knocks rests on that word and on whoever lets them in), and a colleague with a computer of their own can read every value in the vault through their employees.
- A compromised host. The agent runs as your user; anyone with that account has the same access.
- A malicious repository. Claude Code's own trust prompt appears before an interactive session starts in a new folder; Orchestrator surfaces it as a question rather than accepting it for you. SDK-managed workers do not get that prompt (the SDK runs non-interactively) and load the project's own
CLAUDE.mdand settings: only use that runtime in folders you already trust. - The packaged macOS app's origin. It is ad-hoc signed, not notarized; Gatekeeper cannot vouch for a copy you did not build yourself.
- The verification command. It is your shell command, executed on the host. Treat project settings as code.
- Prompt injection through project content. Agents read repositories and web pages. The permission system, the high-risk gate and worktree isolation limit the damage; they do not make an agent immune.
- Multi-user separation. There is one owner role. Do not share the owner token.