Secure Agent Workspace
About
A sandboxed, agentic workspace providing secure filesystem, bash, and uv-powered Python execution.
Details
- Author
- HrRodan
- GitHub stars
- 1
- Downloads
- 365
- Categories
- Developer Tools, Infrastructure, Security, Automation, AI
Jump to
- Full project lifecycle (uv init, add, run)
- Secure bash execution with timeouts
- Token-optimized output via RTK (60–90% savings)
- Path-traversal protected filesystem operations
- Multi-layer security (non-root, dropped capabilities, read-only)
- Precision editing with fuzzy matching and syntax validation
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
Secure Agent WorkspaceCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
Pull or build the Docker image, then configure your MCP client (e.g., Claude Desktop) with a docker run command that includes resource limits, security options, and a volume mount to your project directory. Alternatively, use the OpenAI Agents SDK with an MCPServerStdio to invoke the server programmatically. Environment variables such as COMMAND_TIMEOUT and LOG_LEVEL can be set via Docker --env.
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"secure agent workspace": {
"agent-workspace-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--init",
"--memory=2g",
"--cpus=2.0",
"--pids-limit=256",
"--cap-drop=ALL",
"--security-opt=no-new-privileges:true",
"--read-only",
"--tmpfs",
"/tmp:size=64m",
"--tmpfs",
"/home/mcpuser/.cache:size=512m",
"--user",
"1000:1000",
"-v",
"/path/to/your/projects:/workspace",
"ghcr.io/hrrodan/agent-workspace-mcp:latest"
]
}
}
}
}McpServers
{
"agent-workspace-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--init",
"--memory=2g",
"--cpus=2.0",
"--pids-limit=256",
"--cap-drop=ALL",
"--security-opt=no-new-privileges:true",
"--read-only",
"--tmpfs",
"/tmp:size=64m",
"--tmpfs",
"/home/mcpuser/.cache:size=512m",
"--user",
"1000:1000",
"-v",
"/path/to/your/projects:/workspace",
"ghcr.io/hrrodan/agent-workspace-mcp:latest"
]
}
}🛡️ Agent Workspace MCP Server
A unified Model Context Protocol (MCP) server providing a highly secure, containerized workspace for Large Language Models (LLMs). It acts as an isolated "agentic playground" where agents can autonomously code, test, and debug without risking the host machine.
---
✨ Features
- 🏗️ Full Project Lifecycle: Bootstrap projects with uv init, manage dependencies with uv add, and execute via uv run.
- 🐚 Secure Bash Access: Execute shell commands with mandatory timeouts and merged output streams.
- 🚀 Token-Optimized Output: Integrates RTK (Rust Token Killer) to automatically filter and compress run_bash outputs (like ls, git, and test runners), saving 60-90% of LLM context tokens.
- 📂 Robust Filesystem: Path-traversal protected operations for reading, writing, and searching the workspace.
- 🛡️ Multi-Layer Security: Non-root execution, dropped capabilities, resource limits, and a read-only root filesystem.
- ⚡ Precision Editing: Advanced search_and_replace with fuzzy whitespace matching, indentation preservation, dry-run support, and syntax validation for Python, JSON, JSONL, TOML, and YAML.
- 📊 Real-time Observability: Direct logging to MCP client UI and persistent rotating audit logs.
---
🏗️ Architecture
flowchart TD
Client["MCP Client (Claude / Cursor)"] -- "stdio (JSON-RPC)" --> FastMCP["FastMCP Server"]
subgraph Sandbox ["Docker Sandbox Container (mcpuser)"]
direction TB
FastMCP -. "Intercepts accidental prints" .-> StdioGuard["StdoutRedirector"]
FastMCP -. "Application Logs" .-> Logger["Dual Logger (stderr & .mcp/server.log)"]
FastMCP -- "Tool Calls" --> SecurityGuard["Security & Path Validator"]
subgraph Toolset ["Tool Modules"]
direction TB
SecurityGuard --> FSTools["Filesystem (read, write, list, search)"]
SecurityGuard --> EditTools["Editing (search_and_replace)"]
SecurityGuard --> ExecTools["Execution (run_bash)"]
end
EditTools -- "AST Verification" --> Validator["Syntax Validations (Python, JSON, JSONL, TOML, YAML)"]
ExecTools -- "Process Group (Timeout=60s)" --> Shell["/bin/sh Subprocess"]
Shell -- "Package Mgt & Checks" --> UV["uv Environment / Ruff"]
FSTools -- "Secure I/O" --> Workspace["/workspace Directory"]
EditTools -- "Atomic Writes" --> Workspace
Shell -- "Executes within" --> Workspace
end
Workspace <--"Volume Mount"--> HostFS["User Host Filesystem"]
---
📦 Quick Start
1. Pull or Build the Docker Image
```bashSign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
