How to Configure OpenHands MongoDB Credentials
You set up openhands mongodb credentials by creating a database user with a scoped role. Then you pass that connection string into the agent workspace. Many teams start by giving their coding agent a shared admin user. That fast path lets the agent work right away. Still, broad permissions let an autonomous agent change or drop live collections by mistake. A small prompt error can turn a simple debug task into a production outage. How openhands mongodb credentials work with database roles Ope
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 credentials by creating a database user with a scoped role. Then you pass that connection string into the agent workspace. Many teams start by giving their coding agent a shared admin user. That fast path lets the agent work right away. Still, broad permissions let an autonomous agent change or drop live collections by mistake. A small prompt error can turn a simple debug task into a production outage.
How openhands mongodb credentials work with database roles
OpenHands runs tasks inside an isolated workspace where it executes shell commands and scripts. When the agent needs database data, it reads connection details from workspace variables. Those details point to a specific MongoDB user account. MongoDB controls what that user can do through role-based rules. A role grants privileges to run sets of actions on defined resources. Each role applies to the database where you define it. It can grant access down to a collection level of detail. Note that MongoDB Atlas users have different built-in roles than self-hosted users. Still, both systems build their roles from the same set of privilege actions.
For most agent tasks, you should assign the built-in read role. The read role allows reading all non-system collections and the system.js collection. It permits actions like find, listCollections, listIndexes, dbStats, collStats, and changeStream. It does not permit insert, update, remove, or dropCollection actions. If the agent must change data, teams often look at the readWrite role. The readWrite role includes everything in read plus data change actions. Those extra actions include insert, update, remove, createCollection, createIndex, dropIndex, and dropCollection. Because dropCollection is included, readWrite carries high risk for an autonomous agent. Custom roles let you grant insert or update on one collection while blocking drops.
What native roles solve and what stays exposed
Native MongoDB roles do a great job of controlling who can log in. They also define which collections a user account can read or change. Setting up a strict read role stops an agent from deleting records. It also prevents the agent from dropping indexes or changing schemas during a task.
Still, static database roles only check permissions at the collection level. They do not inspect what individual queries do in flight. First, you still have to place static credentials inside the agent workspace. Anything running inside that container can read those plain text secrets. Second, the read role lets the agent pull every field in a collection. If a collection holds customer records, the agent reads raw emails and phone numbers. It can also pull card numbers or national IDs into the model context. Data masking is needed to rewrite matched fields in results before the agent reads them. Third, if an agent needs write permissions for a fix, native roles are all-or-nothing. You cannot pause a single risky delete command for human approval while allowing safe reads.
Ephemeral Credentials + MongoDB Authentication & Authorization: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
Check MongoDB commands and documents on the wire
MongoDB roles and SCRAM login decide who opens a session. They do not check single commands or redact sensitive fields inside returned documents. With hoop.dev, you run an open-source proxy, a sidecar for your MongoDB. It reads the MongoDB wire protocol and checks commands and bulk writes as JSON while passing login through untouched.
Before a command runs, hoop.dev guardrails check its effect and refuse banned drops or writes with MongoDB error code 13. On the way back, hoop.dev data masking rewrites sensitive fields in returned documents that match your rules. Every command and verdict is logged. See the open-source code on GitHub.
Frequently asked questions
Which MongoDB role is safest for an OpenHands agent?
Start with the built-in read role on a single database, or build a custom role scoped to specific collections. Avoid the readWrite role in production because it allows the dropCollection action.
Do MongoDB Atlas and self-hosted MongoDB use the same roles?
MongoDB Atlas database users have different built-in roles than self-hosted database users. Still, both systems build their roles from the exact same set of underlying privilege actions.
Can native MongoDB roles hide sensitive fields from an AI agent?
No, standard roles grant access down to the collection level, not the field level. Once an agent has the read role on a collection, its queries return all fields including emails and card numbers.
Related guides
In this post