local-mcp: sandboxed local machine tools for agents, with approvals kept out of band

What local-mcp exposes, and what it leaves out

local-mcp is a Rust MCP server that puts local machine capabilities behind MCP tools: file reads, image reads, directory listings, sandboxed file writes and sandboxed commands, plus unsandboxed command execution that has to be approved explicitly.

The omission is as deliberate as the inclusion. The README states that the server intentionally provides no web search and no dedicated network-request tool. That matters if you are comparing it against the usual grab bag of agent tools, because the whole design is about bounding what an agent can reach on the host rather than about giving it the internet.

Image handling is more capable than the rest of the set. get_image returns PNG, JPEG, GIF, WebP, BMP, TIFF and AVIF files as native MCP image content, and relative image paths are resolved from the session working directory.

The session model

Every tool takes a session identifier, and the agent can call session_info with the identifier from your prompt to confirm the working directory and the sandbox roots. That single detail turns the server from a global door into a set of scoped doors: one local-mcp mcp process can serve several independently configured sessions.

The session working directory is simply the directory where the session was started. The README is explicit that there is no separate persistent working directory setting, which removes a class of surprise where an agent quietly operates somewhere you did not expect.

Transport is local only. Each session uses its own IPC endpoint, an explicitly permission-restricted Unix domain socket on Unix, or a named pipe using the Windows default security descriptor. Both the MCP server and the start UI block on I/O rather than polling, so an idle session or a pending approval does not burn cycles on timers.

Sandboxing and what unsandboxed means here

Commands are isolated with the sandboxing code from OpenAI Codex: Landlock plus the Linux sandbox helper on Linux, and Seatbelt through sandbox-exec on macOS. Network access is denied for ordinary commands.

The split is worth stating precisely, because it is the whole security model. Sandboxed calls are always allowed and have no network access. The unsandboxed path runs with the service user's full host permissions and network access, and it asks the approvals process before every call.

That means the dangerous capability is not hidden behind a default. It is behind a prompt, per call, unless you have switched it off for the session. The README also notes that the runtime environment on Nix includes curl and bash, and that Linux builds include bubblewrap, so what a sandboxed command can reach is defined by that environment rather than by your login shell.

Approvals, and how far yolo mode goes

Approvals are managed from the start screen, and the README shows the full sequence alongside the server startup:

cargo build --release

# Run one persistent MCP server (for example through a tunnel):
local-mcp mcp

# In another terminal, start a session in the project directory:
cd ./some-project
local-mcp start

# Or choose a stable session ID (letters, numbers, "-", "_", and "."):
local-mcp start my-project

# Give the printed session ID to the agent in your prompt. The agent includes it
# in each local-mcp tool call.

# In the approvals UI, allow every unsandboxed call for the session:
/permissions yolo

# Manage the current session from the start screen:
/permission ask
/permission yolo
/permission allow ../another-project
/permission revoke ../another-project
/permission list
/permission status

The scope of yolo mode is the part to read carefully. It disables the prompts only for the lifetime of that session, and turning prompts back on is a single command. Permissions can also be granted per path, so a second project directory can be allowed without opening everything.

Watching what the agent actually did

The start screen is not just an approvals prompt, it is a live activity view. It shows file and image reads, directory listings, file edits with unified diffs and line counts, and command start and completion with output, in a compact timeline in the style of Codex.

That is a genuinely different posture from the usual silent tool call. If an agent edits five files while you look away, you come back to a list of what changed and how many lines moved, not a claim that it worked.

Long-running work is handled with a time threshold rather than a heuristic. execute returns its normal result for commands that finish within 30 seconds. Anything longer continues in the background and returns a job identifier, which you check with poll_job or end with stop_job. When you know from the start that a command should run in the background, start_command skips the 30 second foreground wait entirely.

Platform differences you need to plan for

Linux builds produce two binaries, local-mcp and its sibling codex-linux-sandbox, and the README says to install or copy both into the same directory and to make sure bubblewrap is available in PATH. On macOS only local-mcp is needed, because sandboxed commands use the system sandbox-exec at its absolute path.

Windows is the case that needs the most thought. It uses named-pipe IPC and direct argv execution, and it does not currently provide the filesystem and network sandbox that Linux and macOS enforce. As a result execute and start_command require approval on Windows unless the session is in yolo mode, and write_file writes directly to the requested host path rather than into a sandbox root.

The named pipe detail deserves its own line. Windows builds use the default security descriptor, which grants full control to LocalSystem, administrators and the creator owner, and read access to Everyone and anonymous users. Unlike Unix, the server does not install an explicit per-user ACL. Windows builds target MSVC and need Visual Studio Build Tools with the desktop C++ workload, and the README says to build from a Developer PowerShell using cargo build with the locked and release flags.

Building it and what it depends on

Alongside a plain release build, the project is set up for Nix, and the README documents three entry points:

nix run github:OWNER/local-mcp
nix develop
nix build

The OWNER placeholder is in the README as written, so you will need to substitute the repository owner.

Cargo.toml tells you how tightly this is coupled to Codex. Alongside clap, tokio, serde, serde_json, anyhow, dirs, uuid and similar, it pulls four crates straight from the openai/codex repository pinned to one revision, covering the protocol, the absolute path helper and the sandboxing code, with the Linux sandbox helper pulled in only on Linux. Unix targets add libc and a vendored OpenSSL. Several dependencies are pinned exactly, including the alpha rama crates and allocative, because of a hashbrown type incompatibility described in a comment in the file.

The manifest sets edition 2024 and a minimum Rust version of 1.96, which is newer than most toolchains in general use.

Licence, maturity and how it compares

There is a licence discrepancy worth knowing before you use it. Cargo.toml declares Apache-2.0, while the repository metadata reports MIT. The repository does contain a LICENSE file, so check which text is actually in it before redistributing anything.

Maturity is early. The version in Cargo.toml is 0.1.0, there are no published releases, and the last push in view is 2026-08-04.

Against Codex itself, or against an agent's built-in file tools, the difference is that this is a standalone server you point any MCP client at, with its own approvals surface rather than the agent's. Against a general purpose MCP tool bundle, the difference is the refusal: no web search, no network request tool, and a sandbox that denies network access to ordinary commands. If what you want is an agent that can read and edit your files and run commands under a sandbox you can watch, this is aimed squarely at that. If you want the agent to fetch things, it will not.

Editorial conclusion

local-mcp is worth a look if you want an agent to work on files on your own machine and you care about where the boundary sits. The design is specific in the places that matter: sandboxed calls are always allowed and have no network, unsandboxed calls ask first, and approvals live in a session you control rather than in the agent's context. The caveats are platform shaped. On Linux you must ship two binaries and have bubblewrap available. On Windows there is no filesystem or network sandbox at all, execute and start_command need approval unless the session is in yolo mode, and the named pipe uses the default security descriptor that gives read access to Everyone. It is early software: version 0.1.0, no published releases, a Rust toolchain of 1.96, dependencies pinned to a specific Codex revision, and a licence mismatch between the Cargo.toml and what the repository metadata reports. Read the sandbox section of the README before you point it at anything you care about.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. nakasyou/local-mcp on GitHub
4. README