How to Configure Gemini CLI ClickHouse Sandbox
You set up a gemini cli clickhouse sandbox by creating a read-only database user. Then you connect the terminal agent to your test database with those restricted credentials. Engineering teams often build this setup so an AI agent can explore analytical tables. Still, teams often start by reusing an admin account or a broad developer role. When an agent holds broad rights, one bad prompt can drop tables or read private records. How a gemini cli clickhouse sandbox works with native roles Click
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 a gemini cli clickhouse sandbox by creating a read-only database user. Then you connect the terminal agent to your test database with those restricted credentials. Engineering teams often build this setup so an AI agent can explore analytical tables. Still, teams often start by reusing an admin account or a broad developer role. When an agent holds broad rights, one bad prompt can drop tables or read private records.
How a gemini cli clickhouse sandbox works with native roles
ClickHouse manages users, roles, row policies, settings profiles, and quotas through SQL commands. To use SQL access control, an admin first sets up a storage directory on the server. At least one admin account must also hold the access management permission. That admin can only grant privileges that they already hold themselves. When creating the agent account, the admin sets the login method and allowed client hosts. The admin also assigns default roles and user settings for that new account.
To lock down the sandbox, the admin grants read permissions on specific tables or columns. In ClickHouse, you can grant select rights on individual columns of a table. If an agent only has rights to two columns, it can query only those two columns. A query for any other column fails right away. Even a wildcard select fails unless the table contains only those permitted columns. Since version 24.10, admins can also grant select rights across table prefixes using a trailing asterisk. Once this database role is ready, the engineer configures the terminal agent to use that account.
What native database roles solve and what they miss
Native ClickHouse roles and column grants solve the first layer of sandbox security. They decide who can log in and which tables or columns that account can read. If the terminal agent tries to mutate data or read a blocked column, ClickHouse stops it. Quotas and settings profiles also help limit how much memory or time a query can use.
Yet static database grants leave a large operational gap during daily work. Database permissions apply to the whole login session, not to each query in flight. First, a developer still has to store the database password or key on their machine. Second, an allowed column might still hold sensitive customer details like emails or phone numbers. If you block that column, the agent cannot group or count rows by that field. If you allow that column, raw emails, phone numbers, or card numbers flow into the terminal. Third, native roles cannot ask a human for approval before a risky query runs. The database checks who logged in, not what each statement does at runtime.
ClickHouse Access Management + AI Sandbox Environments: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
Why terminal agents need controls per query
AI terminal tools work fast and generate many SQL statements in a single session. An agent might run ten safe schema checks and then run an unindexed full table scan. Or it might pull a sample of rows that includes national IDs or card numbers. Static sandbox credentials treat all of those queries the same way.
Teams often try to fix this by copying production data into a separate test cluster. Then they run scripts to scrub sensitive columns before the agent logs in. That approach takes extra storage and hours of maintenance every week. Worse, test data quickly falls out of sync with real schemas and edge cases. Engineers end up debugging agent queries against stale tables instead of real structures. Managing access at the statement level removes the need to maintain separate scrubbed copies.
Add runtime guardrails and masking beside ClickHouse
Database grants and network rules control who can reach ClickHouse. Even so, an allowed client or agent can send an alter mutation that deletes rows or read raw personal data. In practice, hoop.dev sits inline in the native TCP protocol beside the server as a sidecar for your ClickHouse. For every production query an agent or human sends, hoop.dev decides whether to pass, mask, block, or escalate it for review.
With hoop.dev ClickHouse support, guardrails refuse banned queries before they run or hold risky calls for approval, and data masking rewrites matched string columns in results in memory. Furthermore, hoop.dev holds SOC 2 Type II and is open source on GitHub.
Frequently asked questions
Can ClickHouse restrict an AI agent to specific columns?
Yes, ClickHouse lets admins grant select rights on individual columns within a table. The agent must name those allowed columns in its query because wildcard selects will fail.
Why do wildcard queries fail in a column-restricted ClickHouse sandbox?
ClickHouse blocks wildcard select queries when a user only has access to certain columns. A wildcard query only works if the table holds solely the columns granted to that user.
What happens when an AI agent queries columns with emails or phone numbers?
With native ClickHouse grants alone, the user either reads raw values or gets blocked completely. Adding data masking rewrites matched fields like emails or phone numbers in query results.
Related guides
In this post