effective-potato!

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

Clone the repository:

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

Create a virtual environment and install dependencies:

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

(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:

Build the Docker image (if not already built)
Start the container
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:

Creates a bash script in workspace/.agent/tmp_scripts/task_$taskid$.sh
Writes the command to the script
Makes it executable
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.

Name		Name	Last commit message	Last commit date
Latest commit History 86 Commits
.agent		.agent
.github		.github
.vscode		.vscode
examples		examples
local		local
openweb_exports/effective-potato		openweb_exports/effective-potato
scripts		scripts
src/effective_potato		src/effective_potato
tests		tests
.gitignore		.gitignore
Dockerfile		Dockerfile
Dockerfile.base		Dockerfile.base
IMPLEMENTATION.md		IMPLEMENTATION.md
README.md		README.md
build.sh		build.sh
install-gh.sh		install-gh.sh
mcp-config.json		mcp-config.json
mcp-http.sh		mcp-http.sh
mcp.sh		mcp.sh
pyproject.toml		pyproject.toml
pytest.ini		pytest.ini
requirements-dev.txt		requirements-dev.txt
requirements.txt		requirements.txt
run-tests.sh		run-tests.sh
setup.py		setup.py

Folders and files

Latest commit

History

Repository files navigation

effective-potato!

Features

Ollama Custom build instructions with rocm6.4.4 (STABLE)

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

Ollama other install stuff

Ollama systemd service file

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

verify

Included Packages

Installation

Usage

Running the MCP Server

MCP Configuration (Streamable HTTP)

Available Tools

Tool schemas

execute_command (potato_execute_command)

GitHub tools (github_get_repository / github_clone_repository)

Git workflow helpers

Background tasks at a glance

Development

Running Tests

Project Structure

How It Works

Command Execution Pattern

Example

Environment Configuration

GitHub CLI Integration

Workspace location override

How it works:

License

Contributing

OpenWeb Model Export

OpenWeb One-shot Redeploy

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages