Skip to main content
Glama
Purgatory (p7y)
by csakaszamok

Purgatorium (p9m)

Docs CI License

NOTE

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/p9m is the official marketplace: it points at this repository's plugins/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 -d

Open 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.me name 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.com

Then:

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 yet

Then 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 kata runtime 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 kata runtime runs each sandbox in its own VM (needs a host with KVM). The privileged dind runtime is for development only (Docker Desktop, a laptop) and is not allowed unless ALLOWED_RUNTIMES says 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 tools
add_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_sandboxA
Destructive

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_fileB
Destructive

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_versionB
Destructive

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_keyB
Destructive

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_sandboxC
Read-only

Get sandbox details HTTP GET /sandboxes/{name}

Inputs: name (required), include_keys.

get_sandbox_composeC
Read-only

The starter stack Purgatorium deployed into the sandbox (compose YAML), secrets masked HTTP GET /sandboxes/{name}/compose

Inputs: name (required).

get_sandbox_ssh_keyB
Read-only

The sandbox's generated SSH private key (for ssh -i) HTTP GET /sandboxes/{name}/ssh-key

Inputs: name (required).

get_templateB
Read-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_runtimesA
Read-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_containersB
Read-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_sandboxesB
Read-only

List all sandboxes HTTP GET /sandboxes

Inputs: no named parameters.

list_sandbox_filesB
Read-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_imagesB
Read-only

The sandbox's images in the p9m registry, with secret-scan results HTTP GET /sandboxes/{name}/registry

Inputs: name (required).

list_sandbox_mountsA
Read-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_volumesB
Read-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_keysB
Read-only

Your SSH public keys (they let you into your sandboxes as root) HTTP GET /ssh-keys

Inputs: no named parameters.

list_templatesA
Read-only

List the templates (what runs inside a sandbox) HTTP GET /templates

Inputs: no named parameters.

list_tokensB
Read-only

List personal access tokens (admin: all) HTTP GET /tokens

Inputs: no named parameters.

read_sandbox_fileA
Read-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_mountA
Destructive

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_tokenB
Destructive

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_summaryA
Read-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_iC
Read-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

    B3.1/5.0

    Scored across 38 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count3/5

    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.

    Completeness4/5

    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

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers