Architecture

PGSandbox is a local Rust MCP server in front of a managed local Postgres cluster by default, with optional explicit external Postgres admin profiles. It does not install Postgres versions or use Docker, and the local runtime chooses a high port such as 65432 instead of binding 5432.

This local-first shape is the current deployment boundary, not the permanent product ceiling. A future hosted PGSandbox database platform should preserve the same agent workflow while adding managed compute, auth, tenancy, quotas, billing, and faster clone/fork backends.

Flow

Agent / MCP client
        |
        v
PGSandbox
        |
        v
Managed local cluster or explicit Postgres profile
        |
        v
Task-specific databases and roles

Resource model

Each experiment gets one database, one login role, credentials scoped to that database, a TTL, and optional labels for task, repo, branch, or agent. Sandbox role passwords are encrypted before being persisted in metadata.

Profiles

Profiles support multiple Postgres versions or hosts without changing the MCP contract.

{
  "defaultProfile": "external-pg17",
  "profiles": [
    { "name": "external-pg17", "adminUrl": "postgres://postgres:postgres@localhost:6543/postgres" },
    { "name": "external-pg16", "adminUrl": "postgres://postgres:postgres@localhost:6544/postgres" }
  ]
}

Schema snapshots

Schema snapshots are explicit named checkpoints stored under PGSandbox local state. They record sandbox metadata, Postgres version, schema digest version, object counts, and compact fingerprints. They are manual before-states, not automatically refreshed truth.

Local templates

Templates are local pg_dump artifacts plus JSON metadata under PGSandbox state. They can only be created from PGSandbox-owned sandboxes and restore into fresh tracked sandboxes with their own roles and TTLs.

Cloning

The first clone backend creates an empty sandbox, runs pg_dump against the source database with ownership and privileges omitted, and streams the dump into pg_restore connected as the sandbox role. If restore fails, PGSandbox attempts to delete the destination sandbox.

Cleanup

Cleanup can run via the explicit cleanup_expired MCP tool or a scheduled process. It only deletes databases listed in the metadata table and matching the configured prefix.