How to Configure Mastra Neon Sandbox

Published
Length
3 min read

Luis Felipe Dias

All posts

To set up a mastra neon sandbox, give your agent a branched Postgres string. Then restrict that database role so the agent only touches safe tables. Teams often start by handing an agent the default project owner key. That shortcut lets an agent drop tables or read private rows during test runs. A safer setup uses isolated database branches and strict role rules. How the mastra neon sandbox architecture works Mastra is a TypeScript framework that helps teams build and run AI agents. These age

Your coding agents run with your access.

Claude Code reaches prod with a developer's credentials, and approval prompts get clicked through. hoop.dev checks every query, masks sensitive data, and holds risky changes for a human.

To set up a mastra neon sandbox, give your agent a branched Postgres string. Then restrict that database role so the agent only touches safe tables. Teams often start by handing an agent the default project owner key. That shortcut lets an agent drop tables or read private rows during test runs. A safer setup uses isolated database branches and strict role rules.

How the mastra neon sandbox architecture works

Mastra is a TypeScript framework that helps teams build and run AI agents. These agents often need a Postgres database to store memory, state, or app data. Neon provides serverless Postgres that lets you branch your database in seconds. When you combine them, you get a fast test space for agent workflows.

The setup starts inside your database project. You create a child branch from your main database snapshot. This new branch holds an exact copy of your schema and test data. Next, you create a dedicated Postgres role inside that branch for the agent. You grant this role permission to read or write only specific tables.

Finally, you pass the branch string to your agent tool setup. When the agent runs a task, its database tool logs in with that role. The agent can now run SQL queries against the branched database. Any schema changes or bad writes stay inside that isolated branch. Your main database stays untouched while the agent tests its logic.

Why teams isolate agent database branches

AI agents do not always run predictable queries like standard backend code does. An agent might write raw SQL based on a user prompt. If the prompt is vague, the agent might update the wrong table rows. Branching gives developers a quick way to reset the database after a bad run.

Teams also use branches to run parallel agent evaluations in continuous integration pipelines. Each test run gets its own fresh database state. When the test finishes, the pipeline deletes the branch to save storage costs. This workflow keeps test data clean across dozens of daily agent runs.

What native database roles solve and what they miss

Native Postgres roles and branches solve the problem of initial login scope. They decide which user can log in and which tables that user sees. If an agent tries to drop a forbidden table, Postgres blocks the command. Branching also makes sure that test writes never corrupt production tables.

AI Sandbox Environments + End-to-End Encryption: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

Still, static roles cannot inspect what individual SQL statements do in flight. Once the agent logs in, it has full access to its allowed tables. A role cannot stop an agent from reading all rows in an allowed table by default. If that table holds emails or phone numbers, the agent gets all of them. They enter the model context window right away.

Database branches also copy whatever data lives in the parent branch. If the parent branch has real card numbers or national IDs, the child branch does too. Masking that data at rest takes extra scripts that teams must maintain. Plus, native roles do not pause a risky delete query for human approval. And database logs do not link a bad SQL query back to the user prompt.

Steps to tighten agent database permissions

Start by removing superuser and owner roles from all agent tool configs. Create a separate Postgres role for read tasks and another for write tasks. Give the read role select rights only on the exact columns it needs. Never grant broad schema modification rights unless the agent builds migrations.

Set a hard statement timeout on the database role used by the agent. Agents often write poor joins that lock up database compute resources. A short timeout kills runaway queries before they burn through your compute budget. You should also limit how many concurrent sessions that role can open.

Review your parent branch data before you spin up child sandboxes for agents. Remove or scrub tables that hold live secrets, tokens, or customer records. When agents need to query tables with sensitive fields, rewrite matched fields in results. This keeps raw emails and phone numbers out of external model prompts.

Run guardrails and masking on the Postgres connection

Role grants and firewall rules are needed setup. Setup alone cannot check single SQL statements or mask sensitive rows in a response. By design, hoop.dev is an open-source proxy that sits beside Postgres, RDS, or Aurora as a sidecar for your Postgres. Clients and agent tools keep their credentials and point their connection string at the listener.

On each query, hoop.dev guardrails refuse disallowed drops, deletes, or table reads before they run. Next, hoop.dev data masking rewrites sensitive fields in returned rows that match your rules. Furthermore, hoop.dev holds SOC 2 Type II and logs every statement and verdict per resource. Check out the project on GitHub.

Frequently asked questions

Can an AI agent share a database role with my main web app?

No, sharing roles between your web app and an agent is risky. Give the agent its own Postgres role with narrow table and column grants.

Do database branches remove sensitive customer data on their own?

No, a new database branch copies all data from its parent branch. If the parent holds emails or card numbers, the sandbox branch has them too.

How do I stop an agent from running slow queries in a sandbox?

Set a statement timeout on the Postgres role that the agent uses. The database will cancel any query that runs past your time limit.

The query runs. The emails stay hidden.