Smyth Docker Commander

You can run Smyth Docker Commander to spawn an ephemeral Linux sandbox in Docker, access a full TTY, and coordinate both human and AI inputs in real time. It exposes an MCP service over SSE that lets clients spawn a container, send commands, read output, and cleanly stop the sandbox when you’re done.

How to use

Connect a compatible MCP client to the MCP URL exposed by the server. You will be able to spawn a container, interact with its shell, and read output in real time. Use SpawnContainer to start a Linux sandbox, then SendTTYInput or SendTTYInputWithEscapeSequences to type commands. Retrieve the current terminal output with GetScreenContent and finally StopAndDestroyContainer to end the session and remove the container.

How to install

Prerequisites: Node.js v20+ and Docker Desktop/Engine running on your machine.

Install the project dependencies.

Build and start the MCP server.

Configuration and usage examples

{
  "mcpServers": {
    "smyth-docker-sandbox": {
      "type": "http",
      "url": "http://127.0.0.1:PORT/mcp",
      "args": []
    }
  }
}

Tools and capabilities

The server exposes a set of actions you can call from an MCP client to manage a container-driven session. These include: SpawnContainer, SendTTYInput, SendTTYInputWithEscapeSequences, GetScreenContent, and StopAndDestroyContainer.

Collaborative terminal interaction

You can collaborate with AI clients and human users in the same container terminal. Both parties see the same live output and contribute inputs. Use local command mode (F12) for manual control if needed.

Notes, tips, and limits

Docker must be running. The output buffer cap is designed to keep memory use reasonable. A TTY environment is required for proper operation. The default container image is ubuntu:latest, and you can adjust this when spawning a container.

Development and flow examples

A typical flow is: spawn a container, wait for readiness, send a shell command terminated with a carriage return, read the latest output, and stop the container when your task completes.

Troubleshooting

If you encounter errors, verify that Docker is accessible from your host, confirm the MCP URL is reachable, and ensure your client follows the expected input sequences (carriage return terminated commands or escape-sequence aware input). Also check that the server process is running and that you have the necessary permissions to create Docker containers.

Security and access considerations

Limit access to the MCP endpoint in production and consider authentication or network isolation when exposing the MCP URL. Keep container images up to date and follow best practices for running ephemeral sandboxes.

Examples of client flows

1. Start a container
2. Run a command with SendTTYInput or SendTTYInputWithEscapeSequences
3. Read output with GetScreenContent
4. Stop and destroy the container with StopAndDestroyContainer

Development

Build: npm run build
Start (built): npm start
Dev loop: npm run dev

Available tools

SpawnContainer

Pulls the specified image (default ubuntu:latest) and starts a TTY bash session inside a new container.

SendTTYInput

Sends input to the container TTY. Interprets only carriage return (\r) to terminate commands.

SendTTYInputWithEscapeSequences

Sends input and interprets common escape sequences (e.g., \r, \b, \t, \x1b, and octal like \033).

GetScreenContent

Returns the rolling output buffer from the container’s TTY (last ~5–10k characters).

StopAndDestroyContainer

Stops the running container and removes it, restoring the local terminal.