Turnpack runs entirely on your machine. It makes no network requests, needs no API keys, collects no telemetry, and has zero runtime dependencies.
This page says what Turnpack defends against, how, and where each defence stops. If you find a way through one of them, please report it privately.
The caller of every tool is a language model. Usually it is cooperative and occasionally careless. Sometimes it is steered by text it read in your repo, a web page or an issue (prompt injection). So every tool argument is treated as untrusted input, and nothing the model passes can widen what a tool is allowed to touch.
What Turnpack does not try to be is a sandbox for your whole agent. Your AI app very likely has its own shell and file tools. Turnpack's job is to make sure that its tools do not hand the model anything those permission prompts would not.
Every read, search, write and delete is confined to the workspace. The workspace is decided on the server side, from the first of these that applies:
TURNPACK_ROOT: one directory, or several separated by:(;on Windows).- MCP
roots: the folders your app reports for the session. Claude Code and OMP report the project directory. CLAUDE_PROJECT_DIR: set by Claude Code for the servers it starts. It is believed only when the client that connects identifies itself as Claude. Any other app launched from a Claude Code terminal inherits the variable, and for that app it names a different session's project.- The directory the server process was started in, unless that directory is too broad to be a project (see below).
The root argument on a tool call (also accepted as cwd) may select a directory inside that boundary. It cannot leave it: "/", ".." and absolute paths elsewhere are refused with ERR_ROOT_OUTSIDE_WORKSPACE. Whatever name a call uses for the directory, the server resolves it once and passes the tools only the answer.
Inside the workspace, each path is resolved through symlinks before it is checked, including the existing part of a path that does not exist yet. That covers dangling links too: a symlink whose target does not exist yet is followed to where a write would land, so it cannot be used to create a file outside the workspace or inside .git. A symlink in your repo that points outside it cannot be read or written through. Windows drive letters and case-insensitivity are handled.
Windows also gives a file more than one name. .env::$DATA is .env (NTFS stream syntax), .git::$INDEX_ALLOCATION is the .git directory, a name with a trailing dot or space can open the name without it, and GIT~1 is the 8.3 short name of .git. Every fence below compares names, so on Windows all of these spellings are refused with ERR_PATH_ALIAS before any file is opened, in file paths and in root / cwd alike. Short names are detected by asking the file system for the path's real name.
When there is no workspace. Some desktop apps start their servers in your home directory, at the file system root, or in their own install folder, and name no project. None of those is treated as a workspace: searching and editing a whole home directory is not what anyone asked for. A directory is too broad when it is a file system root, the home directory, an operating system or application folder (C:\Windows, Program Files, AppData, /usr, /Applications, ~/Library and the like), or a folder that holds credentials (~/.ssh, ~/.aws, ~/.gnupg, ~/.kube, ~/.docker, ~/.azure, ~/.config/gcloud). Temporary directories are never too broad.
A server started in such a place, with nothing from the list above, has no workspace. Then:
- A call without
rootis refused withERR_NO_WORKSPACEand nothing is read. - A call must pass
rootas the absolute path of an existing directory. A too-broad directory is refused withERR_ROOT_TOO_BROAD. - On Windows, 8.3 short names in that path are written out to the names the file system stores before anything is checked, so a folder reached as
GIT~1is checked as.git. They are not refused outright, because Windows itself spells profile and temp folders that way: a profile folder calledrunneradminshows up in%TEMP%asRUNNER~1. Stream syntax and trailing dots are still refused. - The call is confined to the directory it named, with every check described on this page applied inside it.
- Every
.turnpack.jsonfrom that directory up to the file system root is enforced, so naming a subdirectory is not a way out from under a project's verify allowlist.
Where it stops: in that one situation the model's argument chooses which project a call works in. Nothing stops it from naming a different project on the next call. Your app's approval prompt shows the root it passed. If you want the boundary fixed, set TURNPACK_ROOT (npx turnpack init --client claude-desktop --root <folder> writes it for you), and the model's argument can again only narrow it.
These files are redacted from pack and batch output and refused by ship, unless the call passes allow_secrets: true:
.env,.env.*,*.env,.envrc(but not.env.example,.env.sample,.env.template,.env.schema,.env.defaults,example.env,sample.env,template.env)*.pem,*.key,*.p12,*.pfx,*.ppk,*.jks,*.keystore,*.kdbxid_rsa,id_ed25519,id_ecdsa,id_dsa(their.pubhalves are allowed).npmrc,.pypirc,.netrc,.pgpass,.htpasswd,.git-credentials,.dockercfgcredentials.json,service-account*.json,secrets.{json,yml,yaml,toml},kubeconfig.aws/credentials,.docker/config.json,.kube/config,.git/config*.tfstate,*.tfstate.backup,*.tfvars
Where it stops: the list matches file names, not file contents. A key pasted into config.js is not detected. And allow_secrets is an argument the model can set. The shield stops secrets from leaking by accident, which is how they usually leak. It is not access control.
A batch script is model-written code, so it gets two independent layers.
Layer one, the script's own world. The script runs in a node:vm context that is given no object from the host. That matters because every host object carries a path back to the host's Function constructor, and from there to process. The ctx helpers are defined inside the context and talk to the host through a bridge that passes strings only. eval, new Function, WebAssembly and import() are disabled.
Layer two, the process. The context lives in a separate, short-lived Node process started with Node's permission model:
- no file writes anywhere
- no child processes, no worker threads
- file reads limited to the workspace and Turnpack's own code
- a minimal environment: your API keys and tokens are not passed in
- a memory cap, and a wall-clock limit enforced by the parent, which kills the process
Anything that needs more (ripgrep for ctx.grep, git for ctx.gitStatus) is done by the parent on the script's behalf. The parent decides the workspace and the secret policy itself and does not take them from the child.
The test suite deliberately breaks layer one and checks that layer two still refuses the write, the shell command and the out-of-workspace read.
Where it stops:
node:vmis not a security boundary, and Node describes its permission model as protection against trusted code doing something unintended, not against determined malicious code. Two layers make an escape much harder. They do not make it impossible.- Node's permission model does not restrict network access on Node 22. A script that broke out of layer one could send what it can read.
- The permission model follows symlinks when reading.
ctx.readrefuses symlinks that leave the workspace, but that check is part of layer one. - A script that broke out of layer one could read a secret file directly instead of through
ctx.read. - If your Node build cannot start the runner with the permission model, Turnpack falls back to layer one plus the separate process.
npx turnpack doctortells you which mode you have. TURNPACK_ALLOW_EXEC=1enablesctx.exec, which runs shell commands as you. The tool then stops advertising itself as read-only.
ship writes files and runs commands. That is its purpose, and your AI app should ask you before allowing it. Within that:
- Validate, then write. Every edit, patch hunk, write, move and delete is checked in memory first. A search text that is not found or is ambiguous, a path outside the workspace or a secret file aborts the whole call with nothing written, and the reply lists every problem, not just the first.
- Loose matching never guesses. A search text is tried exactly as written first. Only if it is absent are looser comparisons tried, whole lines at a time: line endings, line numbers copied from a listing, trailing whitespace, indentation, typographic quotes and dashes. A looser comparison is used only when it identifies exactly one place (with
replace_all, every place it identifies). Two candidate places is an error, never a choice. When a looser match is used the reply says which edit and what was ignored. The same applies to the context lines of a patch, except that a patch is applied top to bottom, so a repeated block is taken at its first occurrence after the previous hunk. - An argument is never silently dropped. A call carrying an argument
shipdoes not know, holding a list, an object or a long string, is refused: applying the rest and reporting success would hide that part of the request went nowhere. - Protected paths.
shipnever modifies a.turnpack.jsonor anything inside a.gitdirectory, at any depth, whatever the arguments, and whether the path is named directly or reached through a symlink. The first holds the verify allowlist; the second holds hooks and config that run on your next ordinary git command. Nested repositories and submodules are covered too. - Byte-exact rollback. Snapshots are taken before the first write and verified by SHA-256 when restored. Files that were created are removed, along with directories created for them. Deleted files come back with their original mode.
- Your changes are not rolled back with it. Before restoring a file,
shipchecks that it still holds whatshipwrote. If something else changed it while verify was running (you saved it in your editor), that file is left as it is, the rest are restored, and the reply isFAILED_ROLLBACK_PARTIALwith the file named. - Interruptions. If the server receives SIGINT, SIGTERM or SIGHUP while verify is running, it stops the verify command and restores the snapshots before exiting. If it is ended outright instead (
kill -9, Windows ending the process, a power cut), the snapshots are also in a rollback journal on disk, and the next Turnpack server to start or handle a call restores the files by the same rule; the server that next works in that folder tells the model what was undone. If the app disconnects mid-verify, the server finishes the call, rollback included, before it exits. - No writing through links. A write to a symlink lands on the file it resolves to, after that file has passed every check above. The link itself is never replaced, and a path that turns out to be a link at the moment of writing is refused.
- Text only. Search-and-replace edits and patches are refused on files that are not valid UTF-8, so bytes the edit never mentioned cannot be corrupted. A move carries the file's bytes and permission bits unchanged.
- One at a time. Concurrent
shipcalls are queued. - No waiting on leftovers.
shipreturns when the verify command itself exits. A background process the command leaves behind (a dev server a test started and never stopped) does not hold the call, or the calls queued behind it, open.
The verify allowlist is optional. Put this in .turnpack.json at the workspace root:
{
"enforceVerifyAllowlist": true,
"allowedVerify": ["npm test", "npx tsc --noEmit", "pytest"]
}A call may name a subdirectory as its cwd. Every .turnpack.json from that directory up to the workspace root is enforced, so stepping into a subdirectory does not step out from under the list.
A command is accepted only if it equals an entry exactly. Extra arguments are refused by default, because arguments change what a command runs: npm test --prefix other/ and node --test --import ./x.mjs are not the commands you approved. To allow trailing arguments for one command, end its entry with * (for example "pytest *"). Even then, anything containing ; & | < > $ ( ), backticks or newlines is refused, so pytest && curl … | sh does not pass. If the file exists but is not valid, verify is refused rather than allowed.
Where it stops:
- The verify command runs your project's code, and
shipedits your project's code, including thetestscript inpackage.jsonor aMakefiletarget, in the same call if it likes. The allowlist stops the agent from launching commands you did not approve, such as a deploy script orcurl … | sh. It does not stop a hijacked agent from changing what an approved command does. For that you need review, or a sandbox around the whole agent. - After
kill -9, a crash or a power cut during verify, the edits stay on disk until a Turnpack server starts or handles a call on the same machine. If the system has given the dead process's ID to a new process, that is once the call's own time limit has passed. If the journal cannot be written (disk full, a read-only state folder, more than 64 MB of original bytes),shipwarns once and only the in-memory rollback applies. - Rollback restores files
shipchanged. It does not undo what the verify command did: a migrated database, generated files, a published package. shipcannot tell your save from a verify command that rewrites the files being shipped (a formatter with--fix). Either way those files are left as they are and the reply says which.- A process the verify command leaves running is not stopped by
ship. On a timeout the command and its process tree are killed, but a process that detached itself from that tree survives. - Without the allowlist,
verifyis an arbitrary shell command chosen by the model. - An app that runs the model's shell commands in a sandbox (Codex does) does not run MCP servers in it. A verify command therefore runs with your normal permissions, outside that sandbox. The app's approval prompt for the
shiptool is the gate, and the allowlist narrows what can pass through it. - To help the model pick the right command, the server reads the project's own files (
package.jsonscripts,Cargo.toml,go.mod,pytestconfig, aMakefile, an enforced.turnpack.json) and names the check it finds. It only names it. Nothing is run unless a call passes it asverify.
- Argument handling. Search patterns are passed to ripgrep as data (
-e pattern -- path), never as flags. - Runaway patterns. When ripgrep is missing, or rejects a pattern it does not support (look-around, backreferences), search falls back to JavaScript's regex engine, and glob listings are matched with regexes too. Those can take exponential time on the wrong pattern, so that work runs in a worker thread with a five-second deadline and is abandoned at it. One bad pattern costs one call, not the server.
- Overflow files. Oversized
packoutput is written to a per-user cache directory (%LOCALAPPDATA%\turnpack\shards, or$XDG_CACHE_HOME/turnpack/shards, or~/.cache/turnpack/shards) with0700/0600permissions, a 24-hour lifetime and a 10 MB cap. Nothing is written into your repo. - Rollback journal. Before
shipwrites, it copies the original bytes of the files it is about to change to a per-user state directory (%LOCALAPPDATA%\turnpack\journal, or$XDG_STATE_HOME/turnpack/journal, or~/.local/state/turnpack/journal;TURNPACK_STATE_DIRoverrides) with0700/0600permissions, flushed to disk, and deletes the record as soon as the call's outcome is decided. A record is restored only when it was made on the same machine and its process is gone or the call has run past its own time limit. Each path in it is resolved again and checked against the workspace it names, the protected paths and links put there since, before anything is written. What was undone is kept as a short note (folder and file names, no file contents) innotesbeside the journal until a server passes it to the model, or 14 days. Anyone who can write to that directory can already write to your files. - The installer.
turnpack initpreviews every change, backs up each file as*.turnpack.bak, writes atomically, keeps what you added to an existing entry, and skips any config it cannot parse instead of rewriting it. It does not change any app's approval settings. - Supply chain. No runtime dependencies. The release workflow publishes with npm provenance, so a published version can be traced to the commit that built it. The entry
initwrites does not go back to the registry: it starts a file already on your machine (a global install, a checkout, or a copy under~/.turnpack/versions/<version>), so what your apps run changes only when you runinitagain. With--npxit writesnpx -y turnpack@<version> serve, pinned to the version. A hand-writtennpx -y turnpack serveruns whatever is newest each time your app starts. - The call log.
TURNPACK_LOG=<file>is off unless you set it. It records the time, the tool name, the duration, success or failure, the reply size andship's outcome. It never records arguments, paths or file contents, and nothing is sent anywhere. - Loading tools up front. Each tool carries
"anthropic/alwaysLoad": true, which asks Claude Code to show the tools to the model at the start of a session instead of on first use. It changes when about 1,300 tokens of schema enter the context and nothing about what the tools may do. Set"alwaysLoad": falseon the server entry to opt out.
npx turnpack doctorruns the real server and checks the secret shield, the workspace jail and the batch isolation mode on your machine, then starts the server from each AI app's own config. The attack tests are in test/: sandbox escapes and runaway scripts in pack-batch.test.mjs, allowlist smuggling and protected paths in ship.test.mjs, jail, root handling and the no-workspace case in mcp-cli.test.mjs and security.test.mjs, loose matching in edit-match.test.mjs and patches in patch.test.mjs.
Please use GitHub Security Advisories for OnlyTerp/turnpack rather than a public issue. Include the Turnpack version, your OS and Node version, and the smallest tool call that shows the problem. Fixes are credited in the changelog unless you would rather not be named.