How to Configure OpenHands Neon Sandbox

Published
Length
3 min read

Luis Felipe Dias

All posts

To set up an openhands neon sandbox, create an isolated database branch and pass its credentials to the agent runtime. This setup lets AI coding agents run schema changes and test queries without touching live systems. Many teams start by handing the agent a standard database role with broad write rights. When roles are too broad, a bad agent prompt can drop tables or read private user rows. How the openhands neon sandbox architecture works OpenHands runs an autonomous coding agent inside a l

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 an openhands neon sandbox, create an isolated database branch and pass its credentials to the agent runtime. This setup lets AI coding agents run schema changes and test queries without touching live systems. Many teams start by handing the agent a standard database role with broad write rights. When roles are too broad, a bad agent prompt can drop tables or read private user rows.

How the openhands neon sandbox architecture works

OpenHands runs an autonomous coding agent inside a local or cloud container. The agent writes code, runs shell commands, and connects to external data stores. Neon provides serverless Postgres with fast database branching for test workflows. A branch copies the schema and data from a parent database in seconds.

To link the two tools, engineers create a fresh branch for the agent task. The team then makes a dedicated Postgres role for that specific branch. Next, they pass the branch connection string into the agent container as a secret. The agent reads this string from its runtime variables to run migrations and queries.

Each branch acts as an isolated sandbox for that single coding task. When the agent finishes its work, the team reviews the code changes. After the review, the system can delete the temporary database branch right away. This flow stops failed agent experiments from breaking the main development database.

What native branch roles solve and where gaps remain

Native database branching solves the problem of shared state during agent runs. Multiple agents can work at the same time on separate branches without lock conflicts. Postgres roles also let admins restrict which schemas or tables the agent can touch. You can grant read rights on reference tables and write rights on new tables.

Still, native database setups only check who logs in at the start. Once the agent connects, Postgres allows any query that matches the role permissions. A branch copied from production still holds real emails, phone numbers, and card numbers. If an agent queries a user table, those sensitive fields enter the model prompt.

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

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

Static roles also cannot block destructive commands inside the allowed schema. An agent with table modification rights can still drop a core table on its branch. That mistake wastes compute time and forces the developer to reset the test branch. Native database logs also do not link SQL queries back to the human who started the agent.

Best practices for agent database roles

Teams should follow strict rules when setting up database branches for AI agents. First, never connect an autonomous container to a main or production branch. Always point the agent to a child branch that holds synthetic or scrubbed data.

Second, avoid giving the agent the default database owner role. Create a narrow role that only owns the specific tables needed for the task. Set statement timeouts on that role so bad queries do not run forever. Drop the temporary branch and revoke its keys as soon as the task ends.

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

Why use a database branch for an OpenHands agent?

A branch gives the agent an isolated Postgres copy for testing schema changes. If the agent writes a bad migration, the main database stays safe and untouched.

Should an AI agent use the default Neon database owner role?

No, the default owner role has full control over all schemas and data. Always create a restricted Postgres role with access to only the required tables.

How do you handle sensitive data in cloned database branches?

A cloned branch copies all rows from the parent database, including private user details by default. Teams should scrub emails, phone numbers, and card numbers or mask matched fields in results.

The query runs. The emails stay hidden.