How an AI agent reads a database inside your network without opening it up
Giving an AI agent on-premise database access safely: a small runner inside your network that only calls out, read-only queries on PostgreSQL, and no inbound port.
Part of the guide AI employees
You can give an AI agent on-premise database access without exposing the database to the internet. The pattern is a small program, a runner, installed on a machine inside your network. The runner makes outgoing HTTPS calls to the service that hosts the agent, asks whether there is a query to run, runs it locally against the database, and sends the rows back. Nothing connects inward, so no firewall port is opened and the database keeps its private address. In xMap Flows this is the xMap runner, and today it reaches PostgreSQL.
This article is for the person who has to say yes or no to that setup: an IT lead, a data owner, or an operations manager who wants an AI employee to work from the customer table without copying it to a spreadsheet every week. It explains how the runner works, what stops the agent from changing data, a made-up example, the mistakes to avoid, and what a finished AI employee looks like.
The problem with the usual options
A hosted AI agent lives on the public internet. A database on premise, or in a private cloud network, does not. There are three common ways to bridge the two, and two of them are uncomfortable:
- Open the database to the internet, restricted to a list of addresses. It works, but security teams rightly dislike it, and the list needs upkeep.
- Export a file on a schedule. Safe, but the agent always works from yesterday's data, and someone owns a script that breaks quietly.
- Put a small agent inside the network that calls out. The database stays private, the data is live, and the only traffic is outbound HTTPS, which almost every network already allows.
The third option is what a runner is. The same idea is used by build systems and monitoring tools; it is not special to AI.
How the xMap runner works
- An organization admin opens Settings, Advanced, Runners in your network, and adds a runner. Its token is shown once.
- Someone in IT starts the runner on a computer that can reach the database, with Node.js 20 or newer, or with Docker. It is one small program. Settings then shows it as Connected.
- On the Connections page the admin adds a team PostgreSQL connection, sets "Reach it through" to a runner in your network, and picks the runner. The host can be a private one such as 10.0.0.5 or db.internal.
- Pressing Test sends a real sign-in through the runner. If it passes, flows can use the connection.
From then on, when a flow needs rows, xMap Flows leaves a job for that runner. The runner, which keeps asking for work over its outgoing connection, picks the job up, runs the query on your network, and returns the result. The runner stores nothing. If it is stopped, the block that needed it says so in plain words and the run fails cleanly; nothing falls back to another route.
What keeps the agent from changing anything
Read access is enforced in several places, not left to the AI's good behaviour:
- The query is yours, not the agent's. Database query and Database lookup run one SELECT that a person wrote in the block. The AI does not compose SQL.
- One read-only statement. A second statement, or anything that changes data, is refused before it is sent. PostgreSQL runs the query inside a read-only transaction, and the runner checks it again on your side.
- Values are bound, never pasted. A value from a webhook or a flow variable goes in as a parameter, so it cannot alter the query.
- Limits. A query returns at most 5,000 rows, within 20 seconds.
- Admins decide what is reachable. Only team connections can use a runner, and only admins create those. Revoke a runner in Settings and it stops at once.
A second layer is worth adding yourself: give the connection a database user that has SELECT on the few tables or views the AI employee needs, and nothing else. Then even a mistake in a query cannot reach payroll.
A made-up example: a wholesaler's customer table
This company and its numbers are invented. A food service wholesaler in Toronto keeps 3,800 customers in a PostgreSQL database in its own server room. Sales wants two things: a weekly list of new restaurants that are not customers yet, and a chat where reps can ask "is this place already ours, and who looks after it?"
IT creates a view with five columns (name, phone, website, account manager, last order month) and a user that can read only that view. The runner goes on a small server next to the database.
The weekly flow: Schedule on Monday, Area of interest for the delivery area, Nearby places for restaurants and cafes, Only new, then Database lookup set to match by phone and keep only items not in the table. Of 60 new places that week, 9 turn out to be existing customers under another name and drop out. The other 51 are scored by xMap LLM and emailed to the sales lead.
The chat: a Chat trigger, an AI agent with Nearby places and Database lookup linked to its Tools port, and a Reply. A rep types a restaurant's name; the agent finds the place, checks it against the view through the runner, and answers "yes, a customer since March, looked after by Dana" or "not a customer; here is the phone number". The agent decides when to look something up. It does not decide what the lookup query is.
Mistakes to avoid
- Using the application's own database user. It can usually write. Create a read-only user for the AI employee.
- Pointing at a whole table when a view would do. A view with a handful of columns is easier to explain to an auditor and to the AI.
- Running the runner on someone's laptop. When the laptop sleeps, the flows stop. Use a server or a container that stays on.
- Expecting every database to work this way. Only PostgreSQL goes through the runner today. BigQuery and Snowflake are cloud services and are reached directly with their own sign-in.
- Forgetting the big table. A lookup reads up to 5,000 rows a run. For a larger customer list, filter in the SELECT, for example to one region or to active accounts.
- Leaving old runners connected. When a server is retired, revoke its runner. The list in Settings should match what is really running.
What the AI employee looks like in practice
Once the connection exists, the database is one more source in a flow, next to the map, the weather or job postings. Common shapes:
- Start from your rows. Database query brings in branches, sites or customers, each row as an item with its position when the query has latitude and longitude columns. The blocks after it search around each one, score it, or map it.
- Check against your rows. Database lookup marks each lead as known or new, or adds columns such as the account manager.
- Answer from your rows. An AI agent uses the lookup as a tool in a chat or on WhatsApp.
- Write back, if you allow it. Save to my database inserts results into a table, but only when the connection is set to allow writing. It is off unless an admin turns it on.
What reaches the inbox is ordinary: a Monday email of leads with your own customers already removed, or a weekly note on each branch with what changed around it. The difference is that nobody exported anything. Start from Prospects not yet in my CRM and swap its lookup for Database lookup, or from New openings into my database if you want results written back. The runner help article has the installation steps, and the AI employees guide explains how these flows are managed day to day. If your security team has questions first, book a call.
Questions
Does the runner need an inbound firewall rule?
No. It only makes outgoing HTTPS calls to xMap Flows. Nothing connects into your network, and the database keeps its private address.
Can the AI agent write or delete data?
Not through Database query or Database lookup: they accept one read-only SELECT, run in a read-only transaction and are checked again by the runner. Writing is a separate block that works only when an admin has allowed it on the connection. A read-only database user adds a further guard.
Which databases can be reached through a runner?
PostgreSQL only, today. BigQuery and Snowflake are reached directly over the internet with their own sign-in, without a runner.
What happens if the runner goes offline?
The block that needs it fails with a message saying the runner is not connected, and the flow's owner is told as for any failed run. No other route to the database is tried.
Does the AI model see my data?
Only the rows your query returns, and only when an AI block reads them. Keep the SELECT to the columns the job needs. Organizations that want the AI blocks to run on their own AI provider account can set that up as well.
Who can add a runner?
Organization admins. They create the runner, and they create the team connection that uses it, so they control what flows can reach.
Templates that do this
Read next
More on ai employees and automation · Every article · Templates