How to Configure OpenHands Postgres Sandbox

Published
Length
3 min read

Luis Felipe Dias

All posts

You set up an openhands postgres sandbox by creating a limited database role for the agent. Then you pass those restricted login keys into the isolated container runtime. Engineering teams often connect AI coding agents to test databases to debug queries and check schemas. Still, many teams reuse broad developer credentials to save time during setup. When an autonomous agent holds write or admin rights, one bad prompt can drop tables. Overly broad roles also expose sensitive user columns during

AI Sandbox Environments + End-to-End Encryption: the complete guide

Architecture patterns, implementation strategies, and security best practices. Delivered to your inbox.

Free white paper. No spam. Unsubscribe anytime.

You set up an openhands postgres sandbox by creating a limited database role for the agent. Then you pass those restricted login keys into the isolated container runtime. Engineering teams often connect AI coding agents to test databases to debug queries and check schemas. Still, many teams reuse broad developer credentials to save time during setup. When an autonomous agent holds write or admin rights, one bad prompt can drop tables. Overly broad roles also expose sensitive user columns during routine code tasks.

How to set up an openhands postgres sandbox

A safe setup starts inside PostgreSQL before you launch the agent container. You first create a dedicated group role for your automated coding tools. PostgreSQL lets teams set up group roles to manage rights across many users. You then create a specific login user for the agent and add it to that group.

Next, you lock down what the PUBLIC role can do inside your database. In PostgreSQL, the special role name PUBLIC gives rights to every role on the system. By default, PUBLIC gets the right to connect and make temporary tables on databases. It also gets the right to run functions and procedures. The database owner must revoke these default rights so the agent starts with zero privileges.

Schema creation rules also need a close check during setup. In PostgreSQL 15 and later, regular users cannot create objects in the public schema by default. Older databases, or systems upgraded from older versions, still allow this behavior. On those older systems, an admin must revoke create rights on the public schema from PUBLIC.

Finally, you grant the agent group read rights on safe tables or specific columns. The PostgreSQL select privilege allows reading from a full table or just specific columns. This same privilege also lets the user export data out of the table. By granting select on safe columns only, you keep secret fields out of basic queries.

What native database roles solve and what they miss

Native PostgreSQL privileges are great at controlling who can log in and read specific tables. They stop an agent from dropping tables or changing schema definitions in your test database. Column grants also block the agent from querying password hashes or billing tables directly.

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 database roles only check permissions at login and table access time. They do not inspect what individual queries do while they run in flight. Once an agent has select rights on a table, it can pull every row at once. Native roles cannot pause a risky command to ask a human for approval first. They also cannot rewrite emails, phone numbers, card numbers, or national IDs inside query results. Also, storing long-lived database passwords inside agent settings creates a secret management risk. If the agent logs its environment variables, those static database keys leak into plain text.

Why runtime controls matter for AI database sessions

AI coding agents work fast and run many queries without human review. A sandbox needs more than a static username and password to stay safe. Teams need a way to keep database passwords out of the container completely. They also need a way to inspect every query before it hits the database engine. Dynamic data masking rewrites matched fields like emails or card numbers in query results. This lets the agent test real schema shapes while keeping raw personal data out of prompts.

Check every Postgres query on the wire

Database roles and network rules decide who can open a session. They do not read what each SQL statement does after login. With hoop.dev, you run an open-source proxy, a sidecar for your Postgres. It runs beside your database and reads the Postgres wire protocol. Your apps and agents keep their login details and change only the host and port in the connection string their tool uses.

Before a query runs, hoop.dev guardrails check the statement by its effect, table, or pattern. They refuse bad deletes or drops with a real Postgres error. On the way back, hoop.dev data masking rewrites sensitive values in returned rows based on your rules. Every query and verdict goes to the audit trail. Furthermore, hoop.dev holds SOC 2 Type II, is MIT licensed, and generates evidence for HIPAA, GDPR, and PCI DSS. See the code on GitHub.

Frequently asked questions

Can I limit an OpenHands agent to read only specific columns in PostgreSQL?

Yes, PostgreSQL lets you grant the select privilege on specific columns of a table or view. The agent will only be able to read the exact columns you list in the grant.

Why can my sandboxed agent still create tables in the public schema?

Databases running versions before PostgreSQL 15 let the PUBLIC role create objects in the public schema. You must revoke the create privilege on the public schema from PUBLIC to stop this.

Does revoking select on a column stop data exports?

Yes, the PostgreSQL select privilege controls both standard read queries and data exports from that object. If an agent lacks select rights on a column, it cannot export that column either.

Save the open-source gateway.

hoop is MIT-licensed infrastructure for controlling how AI agents reach production data. Star hoophq/hoop so you can inspect it, deploy it, or share it when your team starts governing agent access.