Purgatory (p7y)
OfficialManage Purgatorium (p9m) self-hosted Docker sandboxes and their supporting resources through an MCP API.
Identify the caller and inspect server options: runtimes, templates, sandbox summaries, and current account.
Create, list, inspect, start/wake, stop/sleep, restart, keep awake, deep-sleep, archive, and update sleep settings for sandboxes (CPU, memory, runtime, template, idle/deep-sleep timeouts, SSH keys; admin can assign owner).
Inspect sandbox internals: starter compose YAML, containers, volumes, and files; list/read/write/create/delete files and folders.
Manage host-folder mounts into sandboxes (admin) and view a sandbox's existing mounts.
Manage Docker/project access: rotate Docker certificates, generate a single-use project link containing Docker keys, and list/delete sandbox registry image versions.
Manage SSH access and API tokens: list/add/delete personal SSH keys, get/generate sandbox SSH keys, list/create/revoke personal access tokens (optionally restricted to one sandbox).
Provides each sandbox with its own Docker daemon (Docker-in-Docker), allowing agents to create and manage isolated Docker environments and deploy containerized applications.
Offers an optional Portainer UI within sandboxes for managing Docker containers and services.
Provides TLS addresses for Redis, enabling secure access to Redis instances within sandboxes.
Purgatorium (p9m)
Early, before 1.0. It works and is tested (CI on every change, releases with a changelog), but expect rough edges, and breaking changes between minor versions.
Self-hosted sandboxes for your team and their AI agents: everyone gets their own Docker, every app gets a URL, idle sandboxes sleep.
Think of it as a self-hosted Vercel for the apps your team and its agents spin up. Today you deploy with docker compose; git-based builds are on the roadmap.
About 10 seconds from New sandbox to your own Docker and a public URL for your app; a sleeping sandbox is back in under 10. (Measured with the images already pulled: the first sandbox on a new server also downloads them.)
Its own Docker daemon for every sandbox (with a Portainer UI if you want one)
A public URL for every app, and TLS addresses for Postgres, Redis and SSH
Sleeps when idle, wakes on the next request; a delete archives, nothing is lost
Made for agents: tokens limited to one sandbox, an agent guide, an MCP server and a Claude Code plugin (
/plugin marketplace add p9m-team/p9m, then/p9m:init <address>gets each project a sandbox: users need no web UI, only the admin has one).p9m-team/p9mis the official marketplace: it points at this repository'splugins/p9m, so use that name, not this repository's
Hide the complexity. Keep it simple. Focus on what matters.
Purgatorium abstracts away infrastructure complexity and operational overhead, providing an intuitive user experience that lets users focus on their work and business goals rather than managing the underlying technology.
Why Purgatorium, and how it compares with a laptop, a cloud PaaS, a shared Docker host, Coolify and a VM for everyone · How it works: the components (Docker-in-Docker, frp, Traefik, Sablier), a sandbox's lifecycle and the path of a request
The same from a script or an agent
All real runs, in real time; press one to watch it.
With curl through the API, by an agent over the MCP server, and the MCP server by hand (JSON-RPC over HTTP, so even curl can call its tools).
Try it on your laptop
With Docker Desktop, or Docker Engine and the compose plugin on Linux, and ports 80 and 443 free (on Windows, in Git Bash or WSL):
mkdir p9m && cd p9m
curl -fsSLO https://github.com/csakaszamok/p9m/releases/latest/download/docker-compose.yml
curl -fsSL https://github.com/csakaszamok/p9m/releases/latest/download/setup.sh | bash # prints the admin password
docker compose up -dOpen http://p9m.lvh.me (lvh.me and all its subdomains point to 127.0.0.1, so no DNS to set up), sign in as administrator with the password setup.sh printed, and press New sandbox. The first one takes a minute or two while the images are pulled; after that about 10 seconds. Its app opens at its own http://<name>-….lvh.me address.
An app takes seconds to open the first time? In Chrome, Settings → Privacy and security → Security → Use secure DNS: with "your current service provider" each new
*.lvh.mename can wait for a slow or filtering resolver. Turn it off, or pick a provider such as Cloudflare (1.1.1.1).
To remove it: delete the sandboxes in the UI first (each is a compose project of its own, so the next step would leave them running), then docker compose down -v in the p9m directory, and delete the directory.
Related MCP server: agent-env-mcp
Install
On a Linux host with Docker Engine, the compose plugin and sysbox, no clone needed. First check the host; it changes nothing:
curl -fsSL https://github.com/csakaszamok/p9m/releases/latest/download/check-host.sh | bash -s -- dev.example.comThen:
mkdir p9m && cd p9m
curl -fsSLO https://github.com/csakaszamok/p9m/releases/latest/download/docker-compose.yml
curl -fsSL https://github.com/csakaszamok/p9m/releases/latest/download/setup.sh | bash -s -- dev.example.com # .env with your domain and random secrets
docker compose up -d
curl -fsSL https://github.com/csakaszamok/p9m/releases/latest/download/check-host.sh | bash # again, in p9m: what is not secure yetThen sign in at http://p9m.<HOST_DOMAIN> (by default http://p9m.lvh.me). Rather read the scripts before running them? Download them instead of piping them into bash: see Install.
When to use something else
Purgatorium is for a team's apps and agents' deployments that should be up at a URL, cheaply, on your own server. For other jobs other tools fit better:
Production that must scale and stay up → a cloud PaaS, or Coolify / Dokploy on your own servers
Untrusted code from strangers → a microVM sandbox such as E2B or Docker Sandboxes (or Purgatorium's
kataruntime on a host with KVM)Writing code in a cloud IDE → Coder or GitHub Codespaces
An agent running short scripts from an SDK → E2B or Daytona
More in how it compares.
Documentation
csakaszamok.github.io/p9m: tutorials, install, configuration, let your agent deploy, MCP, API, and llms-full.txt for agents.
Security: sandboxes run under sysbox, without a privileged container; install it on the server. For code you do not trust, the opt-in
kataruntime runs each sandbox in its own VM (needs a host with KVM). The privilegeddindruntime is for development only (Docker Desktop, a laptop) and is not allowed unlessALLOWED_RUNTIMESsays so. Web apps in a sandbox open only for its owner unless labelled otherwise (details).
Contributing · Security issues · AGPL-3.0
Free to use, also commercially, on your own servers or for your customers. Changed it and people use it over the network? Then they get your changed source too, under the same license (AGPL-3.0). Every product built on Purgatorium says so: Based on Purgatorium (p9m), in its About page and its docs, is marked as changed, and does not take the names "Purgatorium" or "p9m" (NOTICE). Versions up to 0.10.3 were released under Apache-2.0.
Available Tools
38 toolsadd_sandbox_mountA
Mount a host folder into the sandbox (admin)
Admin only, with HOST_MOUNT_ROOTS set: bind-mounts a host folder at or under one of those roots into the sandbox container (its own Docker's apps can bind it from there too). The sandbox's owner gets that folder as root. The sandbox container is recreated: a running sandbox restarts (its apps are unreachable for a few seconds), an asleep one stays asleep, one in deep sleep gets it when it wakes. A host folder that does not exist is an error from Docker, not an empty new folder. HTTP POST /sandboxes/{name}/mounts
Inputs: host (required), name (required), target, readonly.
add_ssh_keyA
Add an SSH public key: it lets you into all your sandboxes with SSH as root HTTP POST /ssh-keys
Inputs: key (required), name.
archive_sandboxADestructive
Archive sandbox
Stops the sandbox, saves its volumes (tar.gz) and config under opt/archive//, then removes containers, volumes and the sandbox directory. Nothing is removed if archiving fails. HTTP DELETE /sandboxes/{name}
Inputs: name (required).
create_sandboxC
Create sandbox HTTP POST /sandboxes
Inputs: cpus, name, owner, memory, +6 more.
create_sandbox_folderC
Create a folder (and its parents) in the sandbox's files HTTP POST /sandboxes/{name}/files/mkdir
Inputs: name (required), path (required).
create_tokenC
Create a personal access token (shown once) HTTP POST /tokens
Inputs: name (required), sandbox, expires_in.
deep_sleep_sandboxB
Put a sandbox into deep sleep now (containers and network down, data kept; the next request or start rebuilds it) HTTP POST /sandboxes/{name}/deep-sleep
Inputs: name (required).
delete_sandbox_fileBDestructive
Delete a file or a folder (with everything in it) of the sandbox's files HTTP DELETE /sandboxes/{name}/files
Inputs: name (required), path (required).
delete_sandbox_image_versionBDestructive
Delete a version of one of the sandbox's images from the p9m registry
The app name is URL-encoded when it has slashes (team%2Fapi for /team/api). An index takes its platform manifests with it; the space comes back at the weekly garbage collection. HTTP DELETE /sandboxes/{name}/registry/{app}/{digest}
Inputs: app (required), name (required), digest (required).
delete_ssh_keyBDestructive
Delete one of your SSH keys (it no longer lets you in, at once) HTTP DELETE /ssh-keys/{id}
Inputs: id (required).
generate_sandbox_ssh_keyB
Generate the SSH key of a sandbox that has none yet (created with SSH) HTTP POST /sandboxes/{name}/ssh-key
Inputs: name (required).
get_sandboxCRead-only
Get sandbox details HTTP GET /sandboxes/{name}
Inputs: name (required), include_keys.
get_sandbox_composeCRead-only
The starter stack Purgatorium deployed into the sandbox (compose YAML), secrets masked HTTP GET /sandboxes/{name}/compose
Inputs: name (required).
get_sandbox_ssh_keyBRead-only
The sandbox's generated SSH private key (for ssh -i) HTTP GET /sandboxes/{name}/ssh-key
Inputs: name (required).
get_templateBRead-only
A template's compose.yaml as written (to show or edit before a create) HTTP GET /templates/{name}
Inputs: name (required).
keep_sandbox_awakeA
Start the sleep countdown over
For a running sandbox: one request through its router, as any visit would, so it sleeps a full idle timeout from now. Does not wake a sleeping sandbox. HTTP POST /sandboxes/{name}/keep-awake
Inputs: name (required).
list_runtimesARead-only
List the runtimes new sandboxes may use (how a sandbox runs: dind, sysbox, kata; ALLOWED_RUNTIMES) HTTP GET /runtimes
Inputs: no named parameters.
list_sandbox_containersBRead-only
The containers in the sandbox's own Docker (the apps of its compose projects and any others) HTTP GET /sandboxes/{name}/containers
Inputs: name (required).
list_sandboxesBRead-only
List all sandboxes HTTP GET /sandboxes
Inputs: no named parameters.
list_sandbox_filesBRead-only
List a folder of the sandbox's files (/root, /home, /srv and /opt, the folders kept over a deep sleep, and the apps' volumes: see list_sandbox_volumes) HTTP GET /sandboxes/{name}/files
Inputs: name (required), path.
list_sandbox_imagesBRead-only
The sandbox's images in the p9m registry, with secret-scan results HTTP GET /sandboxes/{name}/registry
Inputs: name (required).
list_sandbox_mountsARead-only
Host folders mounted into the sandbox
The host folders the administrator mounted into the sandbox (host path, target inside the sandbox, readonly). enabled: whether HOST_MOUNT_ROOTS is set on this server; the admin also gets roots, the folders that may be mounted. HTTP GET /sandboxes/{name}/mounts
Inputs: name (required).
list_sandbox_volumesBRead-only
The volumes of the apps in the sandbox's own Docker; their files are under each one's path, through the files tools HTTP GET /sandboxes/{name}/volumes
Inputs: name (required).
list_ssh_keysBRead-only
Your SSH public keys (they let you into your sandboxes as root) HTTP GET /ssh-keys
Inputs: no named parameters.
list_templatesARead-only
List the templates (what runs inside a sandbox) HTTP GET /templates
Inputs: no named parameters.
list_tokensBRead-only
List personal access tokens (admin: all) HTTP GET /tokens
Inputs: no named parameters.
project_dir_linkA
A single-use link to the project's .p9m folder, with the sandbox's Docker keys
Answers a link that works once, for 5 minutes, and the command that unpacks it into the project (curl -sf "<url>" | tar -x -C "<project folder>"): the .p9m folder with .gitignore, p9m.env and docker/{ca,cert,key}.pem, the keys checked first. Run the command yourself; never copy a key. Then the docker context commands (a context keeps its own copies of the files: remove it and create it again after new keys or any TLS error, with a new link). An expired or used link answers 410: ask for a new one.
HTTP POST /sandboxes/{name}/project-link
Inputs: name (required).
read_sandbox_fileARead-only
Read a text file of the sandbox's files (UTF-8, up to 1 MB) HTTP GET /sandboxes/{name}/files/text
Inputs: name (required), path (required).
remove_sandbox_mountADestructive
Unmount a host folder from the sandbox (admin)
Admin only: removes the host mount on this target (also when HOST_MOUNT_ROOTS is no longer set). The sandbox container is recreated as for adding one. HTTP DELETE /sandboxes/{name}/mounts
Inputs: name (required), target (required).
restart_sandboxC
Restart sandbox HTTP POST /sandboxes/{name}/restart
Inputs: name (required).
revoke_tokenBDestructive
Revoke a personal access token HTTP DELETE /tokens/{id}
Inputs: id (required).
rotate_docker_keysA
New Docker access certificates (enable / rotate)
New CA, server and client certificates for the sandbox's Docker API (they carry -docker.); earlier exports stop working. Restarts the sandbox. HTTP POST /sandboxes/{name}/docker-keys
Inputs: name (required).
sandbox_summaryARead-only
How many sandboxes: allowed, running, asleep, in deep sleep, archived
A user: their own, against their quota (SANDBOX_QUOTA; free = how many more they may create). The admin: the whole server, and by_owner per owner. Asleep = stopped (also one that failed to start); archived = deleted sandboxes kept in the archive, not counted against the quota. HTTP GET /sandboxes/summary
Inputs: no named parameters.
set_sleep_settingsA
Change sleep settings
Changes idle_timeout and/or deep_sleep_after of an existing sandbox. A new idle_timeout recreates only the socat container (a running sandbox's app is unreachable for a few seconds; an asleep one stays asleep) and applies to the next request's Sablier session. A new deep_sleep_after applies immediately. HTTP PATCH /sandboxes/{name}
Inputs: name (required), disk, idle_timeout, deep_sleep_after.
sleep_sandboxC
Stop sandbox HTTP POST /sandboxes/{name}/stop
Inputs: name (required).
wake_sandboxA
Start sandbox
Wakes an asleep or deep-sleeping sandbox. At the owner's limit (running sandboxes, slots, or a full server) it answers 409 with reason and the running sandboxes; {"sleep": "<name>"} puts one of them to sleep first.
HTTP POST /sandboxes/{name}/start
Inputs: name (required), sleep.
who_am_iCRead-only
Who am I HTTP GET /me
Inputs: no named parameters.
write_sandbox_fileA
Upload a file into the sandbox's files (replaces one of the same name); missing folders on its path are made HTTP PUT /sandboxes/{name}/files/content
Inputs: body (required), name (required), path (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 38 tools
Tools are grouped cleanly by resource (sandboxes, files, mounts, SSH keys, tokens, registry, templates) and most actions are distinct. The only real overlap is the lifecycle family — sleep_sandbox/stop, wake_sandbox/start, deep_sleep_sandbox, keep_sandbox_awake, restart_sandbox, set_sleep_settings — where the descriptions carry the distinction rather than the names. An agent can resolve these, but it must read carefully.
The dominant pattern is verb_noun in snake_case (list_sandboxes, create_sandbox, delete_sandbox_file, add_sandbox_mount, generate_sandbox_ssh_key), applied consistently across resources. A few outliers break the pattern: sandbox_summary and project_dir_link are noun phrases, and who_am_i is an idiom rather than verb_noun. Minor deviations only.
38 tools is well past the comfortable 3-15 range and feels heavy; the surface area is genuinely broad (sandboxes, files, mounts, registry, keys, tokens, templates), so most tools do earn a place. Still, splitting into sub-surfaces or merging the many lifecycle verbs would reduce the cognitive load.
CRUD/lifecycle coverage is strong: sandboxes (create, get, list, restart, sleep/wake/deep-sleep, archive/delete, summary), files (list, read, write, mkdir, delete), mounts (list/add/remove), SSH keys, tokens, and registry images. Remaining gaps are small — no rename/move for files, no template create/update (arguably server-managed), and no sandbox duplication — all workaroundable.
Maintenance
Related MCP Connectors
Cloud Linux VMs for your agent: run code, Docker, files and HTTPS previews in a Sandboxer microVM.
Execution platform for AI agents on Firecracker microVMs in the EU. Interactive Linux sandboxes with root, templates for Python, Node.js, Go, Rust and a headless browser, public HTTPS URLs. Background jobs that outlive the connection, batches of up to 1,000 jobs with dependencies, hard cost caps reserved up front, execution receipts with SHA-256, log digests that fit the context. IPv4, dual-stack or IPv6-only with its own public address, allowlists or no network. WASI runtime for small tasks. Idle sandboxes sleep and keep their files. Also REST API, Python SDK and LangChain.
Hosting for AI agents: your AI client deploys Docker apps to live HTTPS URLs over MCP.
Real Linux labs your AI agent deploys, routes and runs, with domains, TLS, DBs and an audit log.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceA throwaway Docker sandbox for agents to run code and shell commands safely.8 npmMIT
- AlicenseNot gradedqualityCmaintenanceProvides a restricted Docker-based sandbox for LLM agents, enabling file operations, command execution, and local Git within an isolated runtime.19 npmMIT
- AlicenseAqualityBmaintenanceEnables AI coding agents to safely execute commands, run tests, and modify project files inside disposable, policy-enforced Docker sandboxes that are isolated from the host machine and its credentials.15MIT
- AlicenseAqualityBmaintenanceEnables AI coding agents to safely execute code, run tests, and build projects inside disposable Docker sandboxes, protecting the host machine through enforced isolation, filesystem snapshots, and network controls.15MIT