An MCP server for executing commands in Docker containers
npm install @codespin/codeboxCodebox is an MCP Server for running commands within Docker containers for specific workspaces. It simplifies the process of executing code and commands in isolated, reproducible environments.
``bash`
npm install -g @codespin/codebox
#### 1 STDIO transport — start the server on stdin/stdout
`bash`
codebox start
For LibreChat:
`yaml`
mcpServers:
codebox:
type: stdio
command: codebox
args:
- start
timeout: 30000 # 30-second timeout for commands
initTimeout: 10000 # 10-second timeout for initialization
#### 2 HTTP/Stream transport — start the server over HTTP
`bash`
codebox http --host 127.0.0.1 --port 13014 --allowed-origins http://localhost:3000
_Options_
| Flag | Default | Purpose |
| ------------------- | ------------------------- | ------------------------------------------------ |
| --host | 127.0.0.1 | Host to bind |--port
| | 13014 | Port to listen on |--allowed-origins
| | http://localhost: | Allowed origins for CORS (* to allow all) |--idle-timeout
| | 1800000 (30 minutes) | Auto-close idle HTTP sessions after milliseconds |
> The HTTP endpoint is /mcp. An MCP client (e.g. @modelcontextprotocol/sdk’s StreamableHTTPClientTransport) should send the initialize request, receive a mcp-session-id header, and include that header on subsequent requests.
#### Adding a Workspace
Register a workspace directory with Codebox:
`bashUsing a Docker image
codebox workspace add [dirname] --image
_Common options:_
| Flag | Purpose |
| ----------------------- | ----------------------------------------------------------------------------------------- |
|
--image | Docker image to use for new containers |
| --container | Name of an existing Docker container to exec into |
| --name | Custom name for the workspace (defaults to the directory name) |
| --containerPath | Path inside the container to mount the workspace (default /workspace) |--network
| | Docker network to connect the container to (useful in Docker Compose environments) |--copy
| | Copy workspace files to a temporary directory before mounting |--idle-timeout
| | Timeout in milliseconds before automatically closing idle workspace tokens (0 to disable) |--run-template
| | Custom template for docker run commands |--exec-template
| | Custom template for docker exec commands |
_Examples:_
`bashRegister current directory, auto-close tokens after 5 min idle
codebox workspace add --image node:18 --idle-timeout 300000
#### Listing Workspaces
`bash
codebox workspace list
`#### Removing a Workspace
`bash
Remove by name
codebox workspace remove my-workspace-nameRemove by path
codebox workspace remove /path/to/workspaceRemove current directory
codebox workspace remove
`$3
Codebox implements the Model Context Protocol (MCP). AI assistants can:
1. List workspaces using the
list_workspaces tool.
2. Open a workspace via open_workspace; returns a workspace token (and a temp copy if copy=true).
3. Execute commands with execute_command or execute_batch_commands, passing the token.
4. Read or write files with write_file or write_batch_files.
5. Close the workspace with close_workspace; cleans up any temporary directories immediately.> Workspace tokens may be closed automatically after their
idleTimeout expires; clients should handle token expiration and re-open if necessary.Workspace Configuration
Workspaces are stored in
~/.codespin/codebox.json:`json
{
"workspaces": [
{
"name": "my-node-app",
"path": "/home/user/workspaces/my-node-app",
"containerPath": "/my-project",
"image": "node:18",
"network": "my_compose_network",
"copy": true,
"idleTimeout": 300000,
"runTemplate": "docker run -i --rm -v \"{{path}}:{{containerPath}}\" --workdir=\"{{containerPath}}\" {{image}} /bin/sh -c \"{{command}}\""
}
],
"debug": true
}
`Fields
-
name: Identifier for the workspace
- path: Host path to the workspace directory
- containerPath: (Optional) Path inside container (defaults to /workspace)
- image: Docker image for new containers
- containerName: Name of an existing container
- network: Docker network to join
- copy: When true, creates a temp copy before mounting
- idleTimeout: Timeout in ms before auto-closing tokens (0 = disabled; default 600 000)
- runTemplate, execTemplate: Custom command templates
- debug: When true, enables verbose MCP logging under ~/.codespin/logs/Copy Mode
When you enable copy mode with
--copy, Codebox will:1. Create a temporary copy of your workspace directory
2. Mount this temporary copy in the container instead of your original files
3. Run commands on the copy, so your original source files are never modified
4. Clean up the temporary directory when the workspace token is closed or the idle-timeout fires
Copy mode is useful for:
- Testing destructive operations safely
- Preventing accidental modifications to your source code
- Executing commands that might create temporary or build files
- Avoiding permission issues with mounted volumes
Note: Copy mode only works with Docker images (
--image), not existing containers (--container).Command Templates
$3
When using
--run-template with a workspace that uses --image, you can use these variables:-
{{image}} — The Docker image name
- {{path}} — The host directory path
- {{containerPath}} — The path inside the container
- {{command}} — The command to execute (escaped)
- {{network}} — The Docker network, if specified
- {{uid}}, {{gid}} — Host user/group IDs for --user$3
When using
--exec-template with a workspace that uses --container, you can use these variables:-
{{containerName}} — The container name
- {{containerPath}} — The working directory inside the container
- {{command}} — The command to execute (escaped)
- {{uid}}, {{gid}} — Host user/group IDs for --user$3
- Alternative container runtime
`bash
codebox workspace add --image alpine:latest \
--run-template "podman run -i --rm -v {{path}}:{{containerPath}} {{image}} sh -c \"{{command}}\""
`- Custom Docker options
`bash
codebox workspace add --image node:18 \
--run-template "docker run -i --rm -v \"{{path}}:{{containerPath}}\" --workdir=\"{{containerPath}}\" --memory=512m --cpus=0.5 {{image}} /bin/sh -c \"{{command}}\""
`Troubleshooting
1. HTTP / CORS — If you see
Origin not allowed, adjust --allowed-origins (or use * in dev).
2. Debug logging — Set "debug": true in ~/.codespin/codebox.json; logs appear in ~/.codespin/logs/.
3. Docker connectivity — Ensure Docker is running, you have proper permissions, and specified containers/networks exist.
4. Idle workspace closed — If tokens disappear, increase or disable their idleTimeout`.MIT