How to Configure OpenHands MongoDB Permissions

Published
Length
3 min read

Luis Felipe Dias

All posts

You set up openhands mongodb permissions by assigning a scoped database role to the agent user. You then pass that user credential to the OpenHands workspace so the agent can run queries. Many teams start by giving the coding agent a shared admin account during early tests. That wide role lets an automated loop modify records or drop collections across the whole database. How openhands mongodb permissions work in native setups OpenHands runs as an automated coding agent inside a workspace con

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 mongodb permissions by assigning a scoped database role to the agent user. You then pass that user credential to the OpenHands workspace so the agent can run queries. Many teams start by giving the coding agent a shared admin account during early tests. That wide role lets an automated loop modify records or drop collections across the whole database.

How openhands mongodb permissions work in native setups

OpenHands runs as an automated coding agent inside a workspace container. When the agent needs to check data or test a fix, it logs in to MongoDB. MongoDB controls what that user can do through role-based rules. A role grants privilege actions on specific database resources. You can scope a role to a whole database or down to a single collection.

Both MongoDB Atlas and self-hosted databases build roles from the same core privilege actions. Still, their built-in role lists differ slightly. For an agent that only inspects schemas or checks documents, teams assign the built-in read role. The read role grants access to all non-system collections in that database. It allows actions like find, listCollections, listIndexes, dbStats, collStats, and changeStream. It blocks insert, update, remove, and dropCollection actions.

If the OpenHands agent must seed test data, teams often switch to the readWrite role. The readWrite role includes every action in the read role plus data changes. It permits insert, update, remove, createCollection, createIndex, dropIndex, and dropCollection. Teams create a dedicated database user for the agent and attach the chosen role. Then they store the connection string in the workspace so the agent can log in.

What native database roles solve and what they miss

Native MongoDB roles do a great job of locking down broad access at login time. Putting the agent on a read role stops accidental deletes or schema drops cold. Defining custom roles at the collection level also keeps the agent out of unrelated tables. This setup handles basic access control before the session even starts.

Still, database roles only decide who logs in and which collections they can touch. They do not inspect what individual commands or queries do in flight. If an agent has the read role on a user collection, it can run find on everything. The database returns full documents, including emails, phone numbers, card numbers, and national IDs. Native collection roles cannot rewrite matched fields in results to hide those sensitive values.

MongoDB Authentication & Authorization + AI Agent Permissions: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

The gap gets wider when an agent needs the readWrite role to fix a bug. Because readWrite includes remove and dropCollection, one bad agent loop can wipe out a collection. Native roles cannot pause a dangerous delete command to ask a human for approval. Plus, putting long-lived database keys inside an agent workspace creates a key leak risk. Teams need a way to check commands in flight and mask sensitive fields in results.

Best practices for scoping agent database roles

Start every agent setup with the smallest role possible for the task. Use the read role by default when the agent only needs to debug data or write queries. Avoid giving the agent database-wide readWrite access on shared databases. Instead, build a custom role that grants read access on most collections and write access on one test collection.

Separate your agent users from human engineer accounts so database logs stay clear. When OpenHands has its own MongoDB user, you can track which queries came from automated runs. Rotate the agent password often, and remove write privileges as soon as the task finishes.

Add command guardrails and field masking beside MongoDB

Collection roles and IP rules control who connects to MongoDB. Yet an active client or agent session can still run a pipeline that writes data or reads raw personal fields. In practice, hoop.dev runs beside your database as a sidecar for your MongoDB. It checks every wire command and result document without changing your drivers or credentials.

Using hoop.dev MongoDB controls, guardrails refuse banned commands before they run. Data masking rewrites matched fields in returned documents in memory. Furthermore, hoop.dev holds SOC 2 Type II, is MIT licensed, and generates evidence for GDPR, HIPAA, and PCI DSS programs. View the project on GitHub.

Frequently asked questions

What MongoDB role should I give an OpenHands agent for debugging?

Assign the built-in read role on the specific target database. It lets the agent run find, listCollections, and listIndexes without allowing insert, update, remove, or dropCollection.

How is the readWrite role risky for automated coding agents?

The readWrite role includes remove, dropIndex, and dropCollection actions alongside basic inserts and updates. An autonomous agent loop can accidentally wipe an entire collection if a script goes wrong.

Can native MongoDB roles mask sensitive fields in query results?

No, native roles only control access down to the collection level. If an agent can read a collection, MongoDB returns the full document including emails or card numbers unless another tool rewrites the results.

The query runs. The emails stay hidden.