This is currently being refactored as an MCP server for Pochi, instead of being an MCP server that provides coding tools. It will be updated to only provide the sandbox'ed Ubuntu 24.04 environment, and remove some of the tools available that are already built in to Pochi.

If you have no heard of pochi please check it out: https://github.com/TabbyML/pochi/

effective-potato!

This project provides an MCP (Model Context Protocol) server that hosts a sandboxed Ubuntu 24.04 Docker container for secure command execution.

Features

• Sandboxed Environment: Ubuntu 24.04 container with development tools

• Script-Based Execution: Commands are executed via temporary bash scripts for reliability

• Workspace Persistence: Mounted workspace directory for file exchange

• Custom Environment: Optional environment variables loaded from local/.env

• Typed Tool Schemas: Many tools validate inputs with Pydantic and expose JSON Schema via list_tools

• Background Tasks: Run long processes in the background and manage them with task tools

• Git Utilities: Execute git commands and review git status/diffs

Ollama Custom build instructions with rocm6.4.4 (STABLE)

• cmake --fresh --preset "ROCm 6" -DOLLAMA_RUNNER_DIR=rocm --install-prefix /opt/ollama -DCMAKE_PREFIX_PATH=/opt/rocm-6.4.4 -DROCM_PATH=/opt/rocm-6.4.4
• cmake --build --preset "ROCm 6" --parallel $(nproc)
• sudo mkdir -p /opt/ollama && sudo chown -R $USER:$USER /opt/ollama
• cmake --install build --component HIP --strip -v
• CGO_ENABLED=1 go build -trimpath -buildmode=pie -o /opt/ollama/bin/ollama .
• cmake --install build --component CPU --strip -v #this will throw an error but it will install the rocm ggml lib I don't know why this fixes things.

Ollama custom build instructions with rocm 7.0.2 (VERY BROKEN - 1 poor response slow token rate, follow ups crash).

• cmake --fresh --preset "ROCm 6" -DOLLAMA_RUNNER_DIR=rocm --install-prefix /opt/ollama -DCMAKE_PREFIX_PATH=/opt/rocm-7.0.2 -DROCM_PATH=/opt/rocm-7.0.2
• cmake --build --preset "ROCm 6" --parallel $(nproc)
• sudo mkdir -p /opt/ollama && sudo chown -R $USER:$USER /opt/ollama
• cmake --install build --component HIP --strip -v
• CGO_ENABLED=1 go build -trimpath -buildmode=pie -o /opt/ollama/bin/ollama .
• cmake --install build --component CPU --strip -v #this will throw an error but it will install the rocm ggml lib

Ollama other install stuff

• sudo mkdir -p /usr/share/ollama/.ollama/models
• sudo adduser --system ollama
• sudo addgroup --system ollama
• sudo usermod ollama -G ollama
• sudo chown ollama:ollama /usr/share/ollama/.ollama
• sudo chown ollama:ollama /usr/share/ollama/.ollama/models

Ollama systemd service file

[Unit] 
Description=Ollama Service After=network-online.target

[Service]
ExecStart=/opt/ollama/bin/ollama serve
User=ollama
Group=ollama
Restart=always
RestartSec=3
Environment="PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin"
Environment="OLLAMA_HOST=0.0.0.0"
Environment="OLLAMA_MODELS=/usr/share/ollama/.ollama/models"
Environment="OLLAMA_LIBRARY_PATH=/opt/ollama/lib/ollama:/opt/ollama/lib/ollama/rocm"

[Install]
WantedBy=default.target

Prevent GPU hangs around 15 second mark on large models (gpt-oss:120b)

• echo 'options amdgpu queue_preemption_timeout_ms=60000 lockup_timeout=60' | sudo tee /etc/modprobe.d/amdgpu-timeouts.conf

• sudo update-initramfs -u

• sudo reboot

• verify

• cat /sys/module/amdgpu/parameters/queue_preemption_timeout_ms

• cat /sys/module/amdgpu/parameters/lockup_timeout

• in /etc/default/grub set GRUB_CMDLINE_LINUX="amdgpu.dc=0"

Included Packages

The Docker container includes:

• build-essential
• golang-1.23
• rustup (Rust toolchain)
• xorg-dev, xserver-xorg-core
• python3, python3-pip, python3-venv
• gh (GitHub CLI)

Installation

1. Clone the repository:

git clone https://github.com/gavinbarnard/effective-potato.git
cd effective-potato

2. Create a virtual environment and install dependencies:

python3 -m venv venv
source venv/bin/activate
pip install -e '.[dev]'

3. (Optional) Create a custom environment file:

cp local/sample.env local/.env
# Edit local/.env with your environment variables

Usage

Running the MCP Server

To start the MCP server:

source venv/bin/activate
effective-potato

The server will:

1. Build the Docker image (if not already built)
2. Start the container
3. Host the MCP server over Streamable HTTP (default: http://127.0.0.1:8000/mcp)

Alternatively, you can launch via the helper script:

./mcp.sh                # builds venv+package if needed

MCP Configuration (Streamable HTTP)

Start the server (in a terminal) and point your MCP client at its Streamable HTTP URL.

To use effective-potato with an MCP client, add something like the following to your MCP settings:

{
  "mcpServers": {
    "effective-potato": {
      "type": "streamable_http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

Replace /path/to/effective-potato with the actual path to your installation.

An example configuration file is provided in mcp-config.json.

Available Tools

Tool schemas

All published tools expose JSON Schemas via list_tools.

The following tools additionally validate/coerce inputs with Pydantic models:

• potato_screenshot

  • Inputs: { filename?: string, delay_seconds?: integer >= 0 }
  • Behavior: captures a fullscreen PNG into /workspace/.agent/screenshots/<name>.png. The tool returns screenshot_path; clients should surface or fetch the file as appropriate for their UI.

• potato_launch_and_screenshot

  • Inputs: { launch_command: string (required), delay_seconds?: integer >= 0 (default: 2), filename?: string, working_dir?: string (workspace-relative), env?: { [key: string]: string } }
  • Behavior: launches the app, waits, and captures a fullscreen PNG.

• potato_interact_and_record

  • Inputs: { inputs: Array<{ key_sequence?: string, delay?: integer >= 0, type?: 'once'|'sleep'|'repeat' }>, launch_command?: string, venv?: string, duration_seconds?: integer >= 1, frame_interval_ms?: integer >= 10, output_basename?: string, working_dir?: string, env?: { [key: string]: string }, post_launch_delay_seconds?: integer >= 0 }
  • Behavior: optionally launches an app, sends key sequences, and records a WebM into /workspace/.agent/recordings/. Returns video_path plus window/probe info.

• potato_python_run_module

  • Inputs: { venv_path: string (workspace-relative), module: string, args?: string[], background?: boolean }
  • Behavior: runs python -m <module> using <venv_path>/bin/python without activating the venv. If background=true, returns a task_id.

• potato_python_run_script

  • Inputs: { venv_path: string (workspace-relative), script_path: string (workspace-relative), args?: string[], background?: boolean }
  • Behavior: runs <venv_path>/bin/python '<script_path>' without activating the venv. If background=true, returns a task_id.

• potato_python_check_syntax

  • Inputs: { venv_path: string (workspace-relative), source_path: string (workspace-relative) }
  • Behavior: runs python -m py_compile <source_path> using <venv_path>/bin/python.

• potato_pytest_run

  • Inputs: { venv_path: string (workspace-relative), args?: string[] }
  • Behavior: runs pytest using <venv_path>/bin/python -m pytest.

Other published tools (schemas are defined inline and exposed via list_tools):

• potato_execute_command

  • Inputs: { command: string, timeout_seconds?: integer, env?: { [k: string]: string }, background?: boolean }
  • Behavior: runs an arbitrary bash command in the container. If background=true, returns a task id.

• potato_task_start / potato_task_status / potato_task_output / potato_task_list / potato_task_kill

  • Behavior: manage background processes started in the container.

• potato_list_repositories

  • Behavior: list git repos tracked in the workspace.

• potato_select_venv

  • Inputs: { paths: string[] }
  • Behavior: select the best venv candidate and return an activate command.

• potato_find_venvs

  • Inputs: { path?: string }
  • Behavior: searches under path (workspace-relative) for venv roots (e.g. .venv, venv, *_env*, and bin/activate). Returns venv_roots and activations (e.g. source <root>/bin/activate).

Git tools:

• potato_git_add / potato_git_commit / potato_git_pull / potato_git_push (approval-gated)
• potato_git_status / potato_git_diff
• potato_git_checkout / potato_git_branch_create / potato_git_branch_delete / potato_git_merge

GitHub tools (only if gh is available in the container):

• github_get_repository
• github_clone_repository

Note: effective-potato intentionally does not publish general workspace file search/review/edit tools (glob/list/read/search/write/applyDiff). Coding agents typically already provide those primitives; this server focuses on container execution, git operations, and GUI automation. potato_find_venvs is a special-case helper because other tools/workflows depend on quickly discovering venv roots.

For an MCP client, you can inspect each tool’s JSON Schema from the list_tools response to validate arguments before calling.

execute_command (potato_execute_command)

Execute a bash command in the sandboxed container.

Parameters:

• command (string, required): The bash command to execute
• timeout_seconds (integer, optional, default 120): How long to wait before returning; process may continue running
• background (boolean, optional): If true, runs in the background and returns a task_id
• env (object, optional): Extra environment variables for this command

Returns:

• If foreground: exit code and output
• If background: task_id and a hint to use task tools

Example:

{
  "name": "potato_execute_command",
  "arguments": { "command": "ls -la /" }
}

{
  "name": "potato_execute_command",
  "arguments": { "command": "uvicorn app:app", "background": true }
}

Follow-ups for background tasks:

• potato_task_status to poll for completion
• potato_task_output with tail to read logs
• potato_task_kill to stop the process

GitHub tools (github_get_repository / github_clone_repository)

Get details for a GitHub repository. These tools are only available when GITHUB_PERSONAL_ACCESS_TOKEN is set in local/.env.

Parameters:

• owner (string, required): The username or organization
• repo (string, required): The repository name

Returns:

• Exit code and repository details

Example:

{
  "name": "github_get_repository",
  "arguments": {
    "owner": "octocat",
    "repo": "Hello-World"
  }
}

Clone a GitHub repository into the workspace directory with github_clone_repository.

Git workflow helpers

Beyond add/commit/pull/push, the server exposes tools to review changes:

• Review changes:

  • potato_git_status — machine-friendly status (porcelain)
  • potato_git_diff — pending or staged changes; use name_only=true for a quick file list

• Safety on push:

  • potato_git_push is approval-gated; callers must set confirm=true and should obtain explicit user consent

Background tasks at a glance

Any long-running command can be backgrounded via potato_execute_command (background=true) or the Python runners. Manage them with:

• potato_task_list — discover known tasks
• potato_task_status — poll until running=false
• potato_task_output — tail logs with tail: 200
• potato_task_kill — terminate with signal: "TERM" (or "KILL" if needed)

Development

Running Tests

Use the provided harness to set up the environment and run pytest:

./run-tests.sh                # unit tests only (default)
RUN_INTEGRATION_TESTS=1 ./run-tests.sh   # include integration tests

You can pass any extra pytest args through the harness, for example:

./run-tests.sh -q tests/test_container.py::test_validate_and_load_env_file_valid

Project Structure

effective-potato/
├── src/
│   └── effective_potato/
│       ├── __init__.py
│       ├── server.py          # MCP server implementation
│       └── container.py       # Docker container management
├── tests/                     # Test suite
├── workspace/                 # Mounted directory for container
│   └── .agent/tmp_scripts/   # Temporary execution scripts
├── local/
│   ├── sample.env            # Example environment file
│   └── .env                  # Your custom environment (gitignored)
├── Dockerfile.base           # Base image (system packages)
├── Dockerfile                # Runner image (FROM base)
└── setup.py                  # Package configuration

How It Works

Command Execution Pattern

Instead of passing commands directly via docker exec with arguments, effective-potato:

1. Creates a bash script in workspace/.agent/tmp_scripts/task_$taskid$.sh
2. Writes the command to the script
3. Makes it executable
4. Executes the script in the container via docker exec

This approach avoids issues with argument escaping and provides more reliable execution.

Example

For the command ls -ltrah /, the system creates:

#!/bin/bash

ls -ltrah /

And executes it as:

docker exec $containerid$ /workspace/.agent/tmp_scripts/task_$taskid$.sh

Environment Configuration

The local/.env file is loaded and validated at startup. Environment variables defined in this file are automatically exported at the beginning of each command execution script.

Important: The .env file must contain only environment variable assignments (e.g., VAR=value) and comments. Any other content will cause a validation error.

If no local/.env file is present, a warning is printed on startup. See local/sample.env for the format.

GitHub CLI Integration

Workspace location override

By default, the host workspace directory is ./workspace (relative to the repo). To override it, set:

export POTATO_WORKSPACE_DIR=/absolute/path/to/your/workspace

The server mounts this path at /workspace inside the container and writes a readiness file at $POTATO_WORKSPACE_DIR/.agent/potato_ready.json.

To enable GitHub CLI tools (github_get_repository and github_clone_repository), add your GitHub Personal Access Token to the local/.env file:

GITHUB_PERSONAL_ACCESS_TOKEN=your_token_here

The token will be used to authenticate the GitHub CLI when the container starts. Once authenticated, you can use the GitHub tools to list and clone repositories.

How it works:

When you execute a command, the environment variables from local/.env are automatically prefixed into the execution script:

#!/bin/bash

export GITHUB_PERSONAL_ACCESS_TOKEN='5678'
export HF_TOKEN='1234'

# Your command here
ls -la /

This ensures that all environment variables are available to every command executed in the container.

License

[Add your license here]

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

OpenWeb Model Export

To export the custom workspace model (e.g., "effective-potato") from your OpenWeb server, set these env vars in your shell (secrets are not written to disk):

• DEV_OPENWEBAPI_URL (e.g., https://openweb.example.com)
• DEV_OPENWEBAPI_KEY (secret)
• DEV_OPENWEBAPI_SCHEMA (optional)

Then run the helper script:

source venv/bin/activate
export DEV_OPENWEBAPI_URL=...
export DEV_OPENWEBAPI_KEY=...
MODEL_NAME=effective-potato OUTPUT_DIR=./openweb_exports/effective-potato ./scripts/export_openweb_model.sh

The resulting artifact will be written under openweb_exports/<model>/<timestamp>.<ext> so it can be checked into this repository and redeployed on other OpenWeb servers.

Note: These shell helpers are not exposed as MCP tools to avoid easy tampering; run them manually as needed.

OpenWeb One-shot Redeploy

To redeploy a model end-to-end (export → import → register → publish) to another OpenWeb server:

• DEV_OPENWEB_URL or DEV_OPENWEBAPI_URL
• DEV_OPENWEB_KEY or DEV_OPENWEBAPI_KEY
• MODEL_NAME: source model to export (unless MODEL_FILE provided)
• NEW_MODEL_NAME: target model name on destination
• MODEL_FILE: optional pre-existing export JSON (skip export stage)
• DELETE_EXISTING=1: optionally replace existing target
• SET_DEFAULT=1: optionally set as default in workspace
• BASE_MODEL_ID, DESCRIPTION, ACTIVATE: optional overrides for UI registration

Example:

source venv/bin/activate
export DEV_OPENWEB_URL=https://openweb.example.com
export DEV_OPENWEB_KEY=... # secret
MODEL_NAME=effective-potato NEW_MODEL_NAME=silly-pertato SET_DEFAULT=1 \
  ./scripts/redeploy_openweb_model.sh

Notes:

• Secrets are injected at runtime and never written to disk.
• The script is idempotent: if NEW_MODEL_NAME already exists and DELETE_EXISTING is not set, it will warn and keep the existing model.
• UI visibility requires register/update to succeed; the script verifies presence before publishing into the workspace config.