Install and setup

PGSandbox is a local Rust binary for MCP clients. By default it manages a local Postgres cluster under ~/.pgsandbox/ and chooses a high port such as 65432.

The managed local runtime requires initdb, pg_ctl, and postgres on PATH. The clone_database MCP tool additionally requires pg_dump and pg_restore.

Agent-assisted setup

Copy this prompt into your coding agent if you want it to install and configure PGSandbox for you:

Install and configure PGSandbox on this machine.

PGSandbox is a local CLI and stdio MCP server for disposable Postgres
databases. It uses a PGSandbox-managed local Postgres cluster by default. It requires local
Postgres server binaries such as initdb, pg_ctl, and postgres on PATH, but it
does not use Docker or touch any existing Postgres service on port 5432.

Do the following:
1. Detect my OS, shell, available package managers, and MCP client. Supported
   clients are codex, cursor, vscode, claude-desktop, and all. If this session
   is clearly running inside one supported MCP client, configure that client
   without asking. If several clients are installed, prefer the active client and
   ask only if you cannot infer where config should be written.
2. Install pgsandbox. Prefer:
   brew install LVTD-LLC/tap/pgsandbox
   If Homebrew is unavailable, use:
   curl -fsSL https://raw.githubusercontent.com/LVTD-LLC/pgsandbox/main/scripts/install.sh | sh
   If the install script uses ~/.local/bin, make sure pgsandbox is available
   in the current shell PATH before continuing.
3. Run:
   pgsandbox --version
   If another pgsandbox appears earlier in PATH and is missing, broken, or a
   different version, use the absolute path to the healthy installed binary in
   the setup command with --command.
4. Verify the managed local runtime:
   pgsandbox local start
   pgsandbox doctor
   If initdb, pg_ctl, or postgres is missing, explain that local PostgreSQL
   server binaries must be installed. Do not start Docker, stop Docker
   containers, or bind localhost:5432.
5. Configure the MCP client without an admin URL unless I explicitly gave one:
   pgsandbox setup --client <client>
   Use --scope project for Cursor or VS Code only if I ask for project-local
   config. Otherwise use the default user scope.
6. Verify configuration and Postgres connectivity:
   pgsandbox doctor
   If this fails, explain whether the CLI, local Postgres runtime, MCP config,
   or explicit external Postgres connection failed.
7. Run the disposable end-to-end check:
   pgsandbox smoke-test
   This should create, query, and delete a sandbox database.
8. If the active agent prefers CLI commands instead of MCP tools, verify direct
   CLI access with:
   pgsandbox create-database --name-hint cli-check --ttl-minutes 10
   pgsandbox run-sql --database-id <created-id> --sql "select 1" --readonly
   pgsandbox delete-database --database-id <created-id>
9. Tell me exactly which MCP client config was updated and that I need to restart
   the MCP client. After restart, help me verify that the pgsandbox server is
   available.

Constraints:
- Do not run Docker commands, stop Docker containers, bind localhost:5432, or
  mutate an existing developer database.
- Use the managed local cluster by default. Use PGSANDBOX_ADMIN_DATABASE_URL,
  PGSANDBOX_CONFIG, or --admin-url only when I explicitly ask for an external
  profile.
- Do not inline the full admin URL in commands, docs, git-tracked files, shell
  startup files, or summaries. Local runtime output should mask the password and
  point to ~/.pgsandbox/local-postgres.json for the full private URL.
- Do not leave a smoke-test database behind. If cleanup fails, report the
  database id or name so I can delete it.

Homebrew

brew install LVTD-LLC/tap/pgsandbox
pgsandbox setup --client codex
pgsandbox doctor

This uses the LVTD-LLC/homebrew-tap repository, which Homebrew addresses as LVTD-LLC/tap.

From source

cargo install --path .
pgsandbox setup --client codex
pgsandbox doctor

Update

The installed CLI binary is the MCP server process that clients launch. Updating the CLI and restarting the MCP client updates the server. Rerun setup when the binary path, explicit admin URL, selected client, or scope changes.

Homebrew can only upgrade after a newer GitHub release exists and the LVTD-LLC/homebrew-tap formula has been updated.

Homebrew

brew update
brew upgrade LVTD-LLC/tap/pgsandbox
pgsandbox --version
pgsandbox setup --client codex
pgsandbox doctor

GitHub install script

curl -fsSL https://raw.githubusercontent.com/LVTD-LLC/pgsandbox/main/scripts/install.sh | sh
pgsandbox --version
pgsandbox setup --client codex
pgsandbox doctor

Custom install path

curl -fsSL https://raw.githubusercontent.com/LVTD-LLC/pgsandbox/main/scripts/install.sh | PGSANDBOX_INSTALL_DIR=/usr/local/bin sh
pgsandbox setup --client codex --command /usr/local/bin/pgsandbox

Source install

cargo install --path . --force
# or, from GitHub:
cargo install --git https://github.com/LVTD-LLC/pgsandbox --tag v<VERSION> --force

Replace v<VERSION> with the release tag you want to install.

Supported clients

pgsandbox setup --client codex
pgsandbox setup --client cursor --scope project
pgsandbox setup --client vscode --scope project
pgsandbox setup --client claude-desktop
pgsandbox setup --client all

Verify

pgsandbox doctor
pgsandbox smoke-test

Restart your MCP client after setup. In Codex, run /mcp to verify the pgsandbox server is available.

No-Docker quickstart

pgsandbox local start
pgsandbox doctor
pgsandbox smoke-test

This can run while Docker or another developer Postgres owns 5432. The managed local runtime chooses a high local port such as 65432 or the next available port.

Repo workflow

Agents can create a sandbox, optionally call prepare_for_repo with explicit command metadata, then call validate_schema_change to run the repo's schema-change command against the sandbox and receive a compact schema diff.

Migration and seed commands are generic argv arrays. Agents choose the command that fits the repository and PGSandbox injects sandbox database credentials through environment variables.

Troubleshooting

Install initdb, pg_ctl, and postgres for the managed local runtime.
Install pg_dump and pg_restore for cloning and template tools.
Use PGSANDBOX_HOME when ~/.pgsandbox is not writable.
Use list_databases, delete_database, and cleanup_expired for stale sandboxes.
Only pass --admin-url, PGSANDBOX_ADMIN_DATABASE_URL, or PGSANDBOX_CONFIG for intentional external profiles.

npm/npx status

Public npm/npx publishing is deferred. Use Homebrew, the GitHub install script, or source install until a package name, release process, and binary packaging are explicitly chosen.