How to build a text-to-SQL agent that queries your database from a sandbox

On Runtime, 2,000 SQL analysis sessions cost about $15.63 a month. This includes a dedicated IPv4 address your database can allow-list. These are the rates in force on 26 October 2026. The sandbox is billed for the CPU that the queries and the model's pandas code use. The minutes spent waiting on the model and the database cost little. A paid sandbox reaches Postgres, MySQL or any other database port with no setup. Its network rules block every other destination.

The short answer

Put a small runner in the sandbox. Send each query on standard input. Pass the connection string through env, never on the command line:

TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime();await runtime.images.build({ name: "sql-agent", recipe: { pip: ["psycopg[binary]", "duckdb"] } }); // onceconst RUNNER = `import json, os, sysimport psycopgsql = sys.stdin.read()opts = "-c statement_timeout=15000 -c default_transaction_read_only=on"with psycopg.connect(os.environ["DATABASE_URL"], options=opts) as conn:    cur = conn.execute(sql)    cols = [c.name for c in cur.description or []]    rows = cur.fetchmany(200) if cur.description else []print(json.dumps({"columns": cols, "rows": rows}, default=str))`;await using sbx = await runtime.sandboxes.create({  image: "sql-agent",  network: { internet: true, allow: ["db.example.com"], connect: ["db.example.com:5432"] },});await sbx.files.write("/workspace/run_sql.py", RUNNER);// The tool the model calls: run_sql(query).export async function runSql(query: string) {  const run = await sbx.exec(["python3", "/workspace/run_sql.py"], {    stdin: query,    env: { DATABASE_URL: process.env.READONLY_DATABASE_URL ?? "" },    timeoutMs: 30_000,  });  return run.exitCode === 0 ? run.stdout : `error: ${run.stderr.slice(-2000)}`;}console.log(  await runSql("select count(*) from orders where created_at > now() - interval '7 days'"),);

Pythonimport osfrom withruntime import Runtimeruntime = Runtime()runtime.images.build(name="sql-agent", recipe={"pip": ["psycopg[binary]", "duckdb"]})  # onceRUNNER = '''import json, os, sysimport psycopgsql = sys.stdin.read()opts = "-c statement_timeout=15000 -c default_transaction_read_only=on"with psycopg.connect(os.environ["DATABASE_URL"], options=opts) as conn:    cur = conn.execute(sql)    cols = [c.name for c in cur.description or []]    rows = cur.fetchmany(200) if cur.description else []print(json.dumps({"columns": cols, "rows": rows}, default=str))'''with runtime.sandboxes.create(    image="sql-agent",    network={"internet": True, "allow": ["db.example.com"], "connect": ["db.example.com:5432"]},) as sbx:    sbx.files.write("/workspace/run_sql.py", RUNNER)    def run_sql(query: str) -> str:  # the tool the model calls        run = sbx.exec(["python3", "/workspace/run_sql.py"], stdin=query,                       env={"DATABASE_URL": os.environ["READONLY_DATABASE_URL"]}, timeout_ms=30_000)        return run.stdout if run.exit_code == 0 else "error: " + run.stderr[-2000:]    print(run_sql("select count(*) from orders where created_at > now() - interval '7 days'"))

The runner returns at most 200 rows for each answer. A select * therefore cannot flood the model's context. A Postgres error comes back as text that the model can read and correct.

Four guards on a model's SQL

A text-to-SQL agent writes queries that nobody reviewed. Use all four guards together, so that no single guard has to be perfect:

The last guard matters most when the model also runs Python. With allow listing only the database's host, code that tries to post the rows to another server is refused. Root inside the sandbox cannot change the rules.

A database password is not an HTTPS credential. So Runtime's secrets cannot keep it out of the sandbox, the way they keep API keys out. Pass the password with env. Runtime never echoes these values back, and journals record them only as a hash. Use a login that can only read.

Reach a database that is not on the internet

With runtime ips reserve, every sandbox of the account sends from one address. No other account uses that address while you hold it (networking). Without credit, a sandbox reaches ports 80 and 443 only. Database ports therefore need an account that has bought credit.

Let the model analyze what it fetched

SQL answers the question, and pandas often explains it. The interpreter in the same sandbox keeps a data frame between the model's steps. matplotlib charts come back as PNG files:

TypeScriptimport { Sandbox } from "withruntime";await using sbx = await Sandbox.create({ network: { internet: false } });await sbx.files.write(  "/workspace/rows.json",  '{"columns":["day","n"],"rows":[["mon",4],["tue",9]]}',);const cell = await sbx.interpreter.run(  "import json, pandas as pd\nr = json.load(open('rows.json'))\n" +    "df = pd.DataFrame(r['rows'], columns=r['columns'])\ndf.describe()",);console.log(cell.results[0]?.data["text/plain"]);

For an agent that should explore a schema on its own, the Postgres server in Runtime's MCP catalog starts inside the sandbox with one call (MCP servers in a sandbox).

What a SQL agent needs

What it costs

Take 2,000 sessions a month. Each keeps a 2 vCPU, 4 GiB sandbox running for 10 minutes while the model asks several questions. The queries and pandas cells use 45 CPU-seconds. The account holds one dedicated IPv4 address:

Without the dedicated address, the total is $10.63. Runtime charges $0.025 per vCPU-hour of measured CPU and $0.0075 per GiB-hour of memory. Custom domains, TCP ports and IPv6 are included (pricing).

Start

Terminalnpx withruntime sandboxes run -- sqlite3 --version

Approve the browser link once. Database ports beyond 80 and 443 open after the account's first top-up.

Related: data analysis agent, spreadsheet analysis, egress control, run untrusted LLM code.

Sources

• PostgreSQL client connection defaults: statement_timeout in milliseconds and default_transaction_read_only, read 26 October 2026.

Facts on this page were checked on 26 October 2026.