How to Configure OpenHands Neon Permissions

Published
Length
3 min read

Luis Felipe Dias

All posts

You set up openhands neon permissions by making a limited Postgres role inside your database branch. Next, you pass that role string into the agent workspace settings before a task starts. Many teams skip this step and hand the AI agent the default database owner key. That shortcut gives the autonomous agent full power to drop tables or read secret rows. A small mistake in an agent loop can wipe out production data in seconds. How openhands neon permissions work in practice OpenHands runs as

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.

You set up openhands neon permissions by making a limited Postgres role inside your database branch. Next, you pass that role string into the agent workspace settings before a task starts. Many teams skip this step and hand the AI agent the default database owner key. That shortcut gives the autonomous agent full power to drop tables or read secret rows. A small mistake in an agent loop can wipe out production data in seconds.

How openhands neon permissions work in practice

OpenHands runs as an autonomous coding agent inside its own isolated container workspace. It writes code, runs bash scripts, and talks to external databases to finish tasks. Neon separates compute from storage and lets teams spin up instant database branches. When you combine these tools, permissions live at two distinct levels.

The first level is the cloud control plane where API keys manage branches and compute endpoints. The second level is the Postgres role system inside each specific database branch. An agent rarely needs control plane keys unless its job is creating new branches. For most coding and debugging tasks, the agent only needs a standard Postgres role.

To keep data safe, you create a dedicated Postgres role inside a non-production Neon branch. You grant that role select, insert, or update rights on specific tables only. You withhold permissions to drop schemas, alter system settings, or read sensitive billing tables. Then you supply that restricted database string to the OpenHands workspace as a secret variable.

When the agent runs a migration script or tests a query, Postgres checks the role rules. If the agent tries to touch a forbidden table, the database blocks the query right away. Using a dedicated child branch adds another safety net for the team. Even if the agent corrupts the allowed tables, you can reset the branch in seconds.

What native database roles solve and what they miss

Native Postgres roles and Neon branches give you a strong starting boundary. They decide which database branch the agent can reach and which tables it can touch. Branch isolation stops an agent test run from slowing down your live customer traffic. Table grants stop the agent from reading tables that belong to other services.

Still, static database roles only check who logs in and which table they target. They do not inspect what individual queries do in flight during a live session. Once an agent has select rights on a users table, it can pull every row by default. If that table holds customer emails, phone numbers, or card numbers, the agent gets them all.

AI Agent Permissions + End-to-End Encryption: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

Static credentials also sit inside the agent container as plain text variables. Because OpenHands can run arbitrary shell commands, a confused prompt can print those secrets into logs. Also, native role setups do not pause dangerous delete statements for human approval. If a role allows writes, the agent can delete every row in that table without warning by default.

Scoping agent database runs for daily tasks

Teams get the best results when they match permissions to the exact task type. For bug triage and schema inspection, give the agent a read-only role on a branch. Neon offers dedicated read-only compute endpoints that enforce this rule at the compute level. This setup lets the agent inspect query plans and row counts without risking any writes.

For feature work that requires schema changes, point the agent at an isolated preview branch. Grant schema change rights only on that scratch branch and never on the main branch. After the agent finishes writing the migration files, a human engineer reviews the diff. The human or a deployment pipeline then applies the tested changes to the main database.

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

Should OpenHands use a Neon project API key or a Postgres role?

Give the agent a scoped Postgres role string for almost all coding and query tasks. Only supply a Neon API key if the agent workflow must create or delete branches.

Can Neon branches protect production data from AI agents?

Yes, child branches isolate writes from the main branch so broken queries do not hurt production. Still, branches copy parent data by default, so sensitive customer fields still exist unless masked.

How do we stop an agent from reading customer PII in a branch?

You can revoke select rights on sensitive columns using native Postgres column grants. You can also use data masking to rewrite emails, phone numbers, and card numbers in query results.

The query runs. The emails stay hidden.