Secure Agent Workspace
About
A sandboxed, agentic workspace providing secure filesystem, bash, and uv-powered Python execution.
Explore
- 🏗️ 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.
---
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
Here is a quick boilerplate showing how to use the containerized workspace programmatically using the standard openai-agents SDK:
``python
import asyncio
from agents import Agent, Runner
from agents.mcp import MCPServerStdio
async def main():
server = MCPServerStdio(
name="Sandboxed Workspace",
params={
"command": "docker",
"args": [
"run", "-i", "--rm", "--init",
The server supports the following environment variables (passed via Docker --env):
| Variable | Default | Description |
|---|---|---|
| COMMAND_TIMEOUT | 60 | Default seconds before run_bash kills a process. |MAX_SEARCH_RESULTS
| | 50 | Maximum results returned by search_workspace. |MAX_READ_SIZE_BYTES
| | 1048576 | Maximum file size for read_file (1MB). |MAX_WRITE_SIZE_BYTES
| | 5242880 | Maximum file size for write_file (5MB). |LOG_LEVEL
| | INFO` | Python logging level (DEBUG, INFO, etc.). |
---
read_file
Read text files with optional `offset` and `limit` (default: 100 lines).
write_file
Create files with **syntax validation** and a **5MB size guard**. Refuses to overwrite existing files by default (`create_only=True`).
list_directory
List contents with `[F]`ile and `[D]`irectory prefixes.
search_workspace
Find files by glob pattern with support for `exclude_patterns`.
run_bash
Execute shell commands in `/workspace` with a 60s timeout. Automatically optimized via RTK to reduce token usage.
search_and_replace
Multi-edit tool with **fuzzy whitespace matching**, **indentation preservation**, dry-run mode, and **syntax validation (Python, JSON, JSONL, TOML, YAML)**.
| Tool | Description |
|---|---|
| read_file | Read text files with optional offset and limit (default: 100 lines). |
| write_file | Create files with syntax validation and a 5MB size guard. Refuses to overwrite existing files by default (create_only=True). |
| list_directory | List contents with [F]ile and [D]irectory prefixes. |
| search_workspace | Find files by glob pattern with support for exclude_patterns. |
| run_bash | Execute shell commands in /workspace with a 60s timeout. Automatically optimized via RTK to reduce token usage. |
| search_and_replace | Multi-edit tool with fuzzy whitespace matching, indentation preservation, dry-run mode, and syntax validation (Python, JSON, JSONL, TOML, YAML). |
---
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.
