AgentExec

A terminal and files for an agent: six MCP tools, over stdio or Streamable HTTP. It has no telemetry, holds no credentials, and depends on nothing but Node 22.15 or later: the build is one file.

node dist/agentexec.js --workspace /path/to/folder --level files

--level decides which tools it offers, each level containing the one before: read (the default) has read, list and search; files adds edit; terminal adds exec_command and write_stdin.

It acts with the rights of whoever starts it. The file tools stay inside the workspace, following links, but that is a check and not a boundary, and at terminal a command can reach anything those rights can. Run it somewhere that is safe for an agent to act.

To serve it over HTTP, name a loopback address and set the token clients must send. MCP is at /mcp:

AGENTEXEC_TOKEN=... node dist/agentexec.js --workspace /path/to/folder --level files --http 127.0.0.1:8123

It has no TLS of its own, so it refuses any other address. To serve it elsewhere, mount it as a library behind something that does:

import { createAgentExec } from "@agentorg/exec";

const exec = createAgentExec({ workspace: "/path/to/folder", level: "files" });
// In a request handler, under any path, once you have decided the caller may reach it:
await exec.handle(request, response);
// When you're done, which stops any command still running:
await exec.close();

If you bundle it into a file of your own, don't start anything off the main thread: its search runs that same file on a worker thread.

Tools

Relative paths are relative to the workspace, and a path that really lies outside it is refused. A failed tool sets MCP's isError; a command that exits non-zero is an answer, not a failure.

Related MCP server: silica-core

The answer from exec_command and write_stdin

Always these four fields, in this order, as the result's text and, for clients that read it, as structuredContent:

exit_code: 0
seconds: 1.204
session_id: none
text:
what it wrote

exit_code is running while the command runs, and session_id is none once it has ended. A command stopped by a signal has 128 plus the signal's number. text is what it wrote since the last answer, cut in the middle past about max_output_tokens tokens (four characters each, 7000 by default), saying how much was cut.

Sessions

A session id is random and is given only to the call that started the command, so agents sharing one server don't touch each other's commands. At most 64 commands run at once; past that a new one is refused, and none is evicted. Closing the connection stops every command still running.

Differences from Codex

exec_command and write_stdin follow OpenAI Codex; see NOTICE. They differ in three ways:

• Commands use pipes, not a terminal, so there is no tty option. Ctrl-C and Ctrl-D are delivered as a signal and an end of input.

• A poll waits at most 30 seconds rather than 300, so that one call stays inside a host's own time limit.

• Sessions are named by random strings, not small numbers.

Tests

npm test runs the conformance suite against the bundled server through the official TypeScript MCP client, over stdio and HTTP, and the official Python one. The Python one needs pip install -r requirements-test.txt, or a Python that has it in AGENTEXEC_PYTHON.

Licence

Apache-2.0.