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

Set up a Postgres MCP server in Cursor

Use PGSandbox when Cursor needs a disposable PostgreSQL database for a migration, SQL check, or test—not access to your production database. Cursor launches the local pgsandbox mcp process over stdio; PGSandbox manages the sandbox database lifecycle.

1. Choose project or user configuration

After installing the binary above, run this from the repository you open in Cursor. Project scope writes .cursor/mcp.json in the current directory. It does not create a separate Postgres cluster for each repository. 

pgsandbox --version
pgsandbox setup --client cursor --scope project
pgsandbox doctor
pgsandbox smoke-test

For configuration shared across your projects, use pgsandbox setup --client cursor --scope user instead; it writes ~/.cursor/mcp.json. Pick the scope you intend to use rather than configuring both while troubleshooting. Setup may install missing PostgreSQL binaries when a supported package manager is available. If that fails, install the required server binaries and rerun setup.

These commands and paths match PGSandbox v0.5.0 and the current setup implementation. See Cursor’s MCP documentation for its project/user configuration and tool-approval controls.

2. Restart Cursor and check the server

Restart Cursor, open the intended repository, and check that its MCP settings list pgsandbox and expose its tools. A successful doctor or smoke-test checks the local runtime; it does not prove that Cursor has loaded the configuration. Keep tool approvals enabled while checking the first workflow.

3. Ask for one disposable database

Use this as an agent instruction, not as a shell command:

Use PGSandbox to create a disposable database for this task.
Run SELECT 1 AS ready in that sandbox using run_sql and show the result.
Do not use an existing application or production database.
When the check is complete, delete only the sandbox you just created.
Do not print database credentials in your explanation.

Check that the query returns ready = 1 and that the deletion succeeds. TTL records expiry; it does not delete a database by itself. If the task is interrupted, inspect list_databases before an explicit delete_database or cleanup_expired call. Continue with the migration and repository workflow recipes and the MCP tool contracts once this check works.

If Cursor cannot find or start PGSandbox

Cursor walkthrough updated October 8, 2026.

Set up a Postgres MCP server in Claude Code

Register pgsandbox mcp as a local stdio server when Claude Code needs a disposable PostgreSQL database for SQL or migration checks. pgsandbox setup --client claude-desktop configures Claude Desktop, not Claude Code. PGSandbox v0.5.0 has no --client claude-code option.

1. Prepare the local database runtime

Install PGSandbox using a method above, then run these commands in your terminal. This prepares Postgres without writing another client's MCP config. 

pgsandbox --version
pgsandbox ensure-postgres
pgsandbox doctor
pgsandbox smoke-test

ensure-postgres can install missing server binaries through a supported package manager; it is not a guarantee that every machine can install them automatically. Resolve any reported runtime error before continuing. A successful smoke test creates, queries, and deletes a sandbox; it does not check Claude Code's connection.

2. Register the stdio server in Claude Code

With Claude Code installed, run this from the repository where you want to use PGSandbox. Local scope keeps the registration private to you and limited to that project; it does not create a separate Postgres cluster. 

claude mcp add --transport stdio --scope local pgsandbox -- pgsandbox mcp
claude mcp get pgsandbox

Start or restart Claude Code in that repository and use /mcp to check the connection. If the executable cannot be found, use its actual absolute path in place of the second pgsandbox in the add command. Check an existing registration before replacing it.

The PGSandbox commands match the v0.5.0 CLI reference and client setup implementation. Registration syntax and scope follow Claude Code's MCP documentation, checked October 9, 2026. This is a stdio configuration recipe, not a claim that every Claude Code version has been tested with PGSandbox.

3. Verify one task through the agent

Ask Claude Code to perform this check, keeping tool approvals enabled:

Use PGSandbox to create a new disposable database for this check.
Run SELECT 1 AS ready with run_sql in that new sandbox.
Confirm ready = 1, then delete only the database created for this check.
Report the query and cleanup outcomes without printing credentials.
Do not connect to an existing application or production database.

If the tools load but database creation fails, troubleshoot with pgsandbox doctor rather than repeatedly changing MCP registration. TTL records expiry, not automatic deletion: after an interrupted task, inspect tracked databases and use an explicit cleanup call. See the tool contracts and repository and migration workflows for the next task. Do not supply an external admin URL for this managed-local recipe.

Using Claude Desktop instead?

Use pgsandbox setup --client claude-desktop and restart Desktop. Its configuration is user-scoped; PGSandbox rejects project scope for that client. This is a separate configuration path from claude mcp add.

Claude setup walkthrough updated October 9, 2026.

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

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.