How to Configure OpenHands MongoDB Least Privilege
You set up openhands mongodb least privilege by assigning scoped database roles to agent accounts. This setup limits the actions an AI agent can run against your collections. Many teams start by giving their coding agents broad database credentials to speed up testing. When an agent holds broad rights, a bad prompt can alter or drop whole collections. Scoping roles before the agent runs is the first step toward safer automation. How openhands mongodb least privilege works in practice OpenHand
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 least privilege by assigning scoped database roles to agent accounts. This setup limits the actions an AI agent can run against your collections. Many teams start by giving their coding agents broad database credentials to speed up testing. When an agent holds broad rights, a bad prompt can alter or drop whole collections. Scoping roles before the agent runs is the first step toward safer automation.
How openhands mongodb least privilege works in practice
OpenHands runs tasks inside a workspace where it can write code and query data stores. To query a database, the agent needs a valid user account and a role. MongoDB controls permissions through role-based authorization on each database. A role grants privileges to perform sets of actions on defined resources. A role applies to the database where you define it. It can grant access down to a collection level of granularity.
MongoDB Atlas database users have different built-in roles than self-hosted deployment users. Both types of users build their roles from the same set of privilege actions. When an agent only needs to inspect records, teams assign the built-in read role. The read role gives read access to all non-system collections in its database. It also covers the system.js collection in that same database. It works through actions like find, listCollections, listIndexes, dbStats, collStats, and changeStream. It leaves out the insert, update, remove, and dropCollection actions.
Sometimes an OpenHands agent must fix data or build a new feature during a task. In those cases, teams often look at the built-in readWrite role. The readWrite role includes every action in the read role plus data change rights. Its actions include insert, update, remove, createCollection, createIndex, dropIndex, and dropCollection. Because dropCollection is part of readWrite, a built-in role can still grant too much power.
Scoping custom roles down to the collection level
To keep an agent safe, you should avoid giving it full readWrite rights everywhere. Instead, you can build a custom role that targets only one or two collections. For example, an agent debugging order logs only needs the find action on that collection. If the agent must write test results, you can grant insert on a scratch collection. You can leave out remove and dropCollection so the agent cannot delete records.
This approach keeps the agent focused on the exact data required for its ticket. You create a dedicated database user just for the OpenHands runtime. Then you attach the custom collection role to that user account. If the agent tries to run a command outside its scope, the database blocks it. Separating human accounts from agent accounts also makes your database logs much easier to read.
Least Privilege Principle + MongoDB Authentication & Authorization: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
What native roles solve and the gap they leave open
Native database roles do a great job of deciding who can log in. They also set hard boundaries on which collections a user account can read or change. If an OpenHands agent has only the read role, it cannot drop a table. That stops many bad accidents before they can hurt your data store.
Still, static roles do not inspect what individual queries do while they run in flight. A read role still lets an agent run a find query across every allowed document. Those documents often hold sensitive fields like emails, phone numbers, card numbers, or national IDs. Native roles grant or deny the whole find action without rewriting matched fields in results. Also, you must store a static database password inside the agent workspace to connect. If a prompt causes the agent to print its environment variables, that password can leak. Finally, if an agent needs one-time write rights, someone must edit the role by hand.
Inspect MongoDB wire traffic in flight
Built-in MongoDB roles govern collection access at setup time. They cannot score command risk per call or mask sensitive document values on the fly. By design, hoop.dev is an open-source proxy that sits next to MongoDB as a sidecar for your MongoDB. It reads every command from mongosh, drivers, or agent tools.
First, hoop.dev guardrails block bad deletes, drops, and write pipelines. Next, hoop.dev data masking rewrites sensitive values in returned documents based on your rules and logs each decision. Explore the repo on GitHub.
Frequently asked questions
Should an OpenHands agent use the built-in readWrite role?
Rarely in shared setups, because readWrite includes remove and dropCollection on every collection. A custom role with only insert or update on one collection is much safer.
Can MongoDB roles limit an agent to a single collection?
Yes, MongoDB roles apply to a database and can grant access at the collection level. You can bind specific actions like find to one collection while blocking all others.
Why is the built-in read role not enough for data privacy?
The read role lets the agent run find across all documents in the allowed collections. It does not mask emails, phone numbers, or card numbers inside the returned documents.
Related guides
In this post