Using it with an agent¶
- Run DataNyx yourself, and read the schema before sharing it.
- Give the agent only the schema, and block its access to the data file or
database. DataNyx produces a schema but doesn't restrict the agent on its own: if it can
open the file, it can still see the data.
datanyx protectsets this up for Claude Code. - Run the agent's code yourself against the real data. Code that prints rows or logs values would expose them if the agent sees that output.
If the agent runs DataNyx itself, its output is still safe to show, as long as you
accept that --keep-name lets it test guesses.
What each setup guarantees¶
| Setup | The agent can't read the data with its own tools | A script the agent writes can't read it |
|---|---|---|
| Nothing set up | No | No |
datanyx protect (a guardrail) |
Yes, for Claude Code's tools, as far as the guard can read a command | No. Running the agent's script on the data is the intended way to work, and a script can print rows |
| Containers (the agent has no copy of the data) | Yes | Yes. The script runs where the data isn't |
The guard is worth having, because it stops the common accidents and turns the right workflow into the easy one. It does not hold against an agent that is trying to get around it, or a script that happens to print a row. If the data is sensitive enough that this matters, use containers.
Enforcing it with datanyx protect¶
datanyx protect ./data # shows what it would change
datanyx protect ./data --write # writes it, then checks that the guard works
datanyx protect ./data --write --command "uv run datanyx" # if datanyx isn't on Claude Code's PATH
datanyx protect --remove --write # takes it all out again
For Claude Code this writes, and only with --write:
.claude/settings.json(orsettings.local.jsonwith--local): deny rules forReadandEditon the paths, plus aPreToolUseguard hook. Anything already in the file is kept..mcp.json: adatanyxMCP server limited to those paths (--no-mcpskips it)..datanyx/protect.json: the protected paths, which the hook reads.
Running it again replaces its own entries rather than adding more, and a settings file that isn't valid JSON is left alone. Paths outside the project are covered by the hook only, since the deny rules are relative to the project.
What the guard refuses. Every refusal says what to run instead.
- Reading, searching or listing a protected path with Read, Grep or Glob, including a Glob pattern that would
match one (
**/*.csv, though**/*.pyis fine if no such file is there). - Shell commands that name one:
cat data/x.csv,ls data,cd data && ...,cat data/*.csv,python -c "open('data/x.csv')", and absolute, Windows-style or Git Bash paths. Commands are read the way a shell reads them, so quotes and escapes (da''ta/x.csv), redirections,$(...), backticks, subshells,{data,src}/x.csv,a & cat data/x.csv,dd if=data/x.csv, here-documents,bash -candevaldon't hide a path. - Git commands that would print the data:
git show HEAD:data/x.csvandgit grep, andgit diff,git showorgit log -pwhen git holds the data, unless narrowed to other paths. - Recursive searches from a folder that has protected data inside it (
grep -r foo .,rg foo,find . -exec ...).datanyx protect --allow-broad-searchallows those. - Changes to the protected data and to what sets the protection up:
.claude,.datanyx,.mcp.json, adatanyx.tomlin any folder, your own~/.claude/settings.json, and the installed DataNyx itself, including reverting them with git (git checkout -- .,git clean,git reset --hard).
What it lets through, because they work with the data without showing it: datanyx schema, synth, check,
scrub, anonymize, run, scan, diff, audit, config, doctor and mcp. Running a script that reads the
data, like datanyx run -- python report.py, is the intended way to work. Within those:
runis refused if it saves the real output to a file (--save-stdout,--save-stderr), or if its command, or any of its options, names the data.anonymize --mapping,restore,pseudonymize,eval,initandprotectare refused, since each writes or shows real values or changes the setup.- Options that loosen what you set up are refused, since each shows something hidden, weakens detection or works
as a way to test guesses:
--keep-name,--keep-names,--keep,--keep-entity,--allow,--keep-numbers,--no-ner,--show-paths,--public-column,--include-examples,--reveal,--allow-urls,--allow-env,--allow-unscanned,--hide,--model,--backend,--detectors,--config,--no-configand theDATANYX_CONFIGvariable. --names-fromcan only name the protected data, and no output option can point at it.- The agent can't edit
datanyx.tomlordatanyx.local.toml, and can't read the local one, which lists the terms you hide.
The hook is the command datanyx hook --require-config. Claude Code runs it before each tool call and reads its verdict; you don't run it yourself, and datanyx protect --write is the way to install it.
It fails closed. The hook is written with onFailure: "block", so if it can't run, tool calls
are blocked instead of slipping through. --write runs the hook once and tells you if the
command doesn't start. A bad command would block everything, so fix it before using Claude
Code in that folder. If .datanyx/protect.json goes missing while the hook is installed, every tool
call is refused until you run datanyx protect again; after protect --remove, restart any Claude Code
session that is still open. The hook uses the program-and-arguments form of a hook command and
onFailure, which need Claude Code 2.1.295 or later: before that, a hook that fails to start lets tool
calls through. --write warns if yours is older.
What it isn't. A guardrail, not a sandbox. It can't see inside a script (one that prints rows, or
writes them to a file, is not caught), or follow a path built from a variable the command sets itself
(D=data; cat $D/x.csv), or know what an unfamiliar program does with its arguments or what a pipe feeds it.
find . -name '*.csv' isn't refused either, so file names can still be listed that way. It governs Claude Code's tools only: other agents, a terminal, or someone
who edits the settings themselves aren't stopped. For hard isolation, use
containers, a separate account with no access to the data, or
a database login that can't read rows.
Hard isolation with containers¶
examples/isolated is a Docker Compose setup
where the agent runs in a container that has no copy of your data:
- The
datanyxcontainer mounts the data read-only and serves the MCP server over HTTP. It runs read-only, with no capabilities, and its network has no route to the internet, so it can't send anything out or be pointed at an internal address. Its audit log is in a volume the agent doesn't have. - The
agentcontainer mounts a workspace for the code it writes and nothing else. It reaches your data only through the MCP endpoint, which answers with schemas, fake rows, checks of its code and anonymized text.
cd examples/isolated
export DATANYX_MCP_TOKEN="$(openssl rand -hex 24)" DATA_DIR=/path/to/your/data AGENT_IMAGE=your-agent-image
docker compose up -d datanyx
docker compose run --rm agent
workspace/.mcp.json is the agent's connection to the server. Use any agent image that speaks MCP over HTTP.
The datanyx service runs a released image from ghcr.io, pinned by digest so the tag can't be moved under you;
a feature newer than that release (see the changelog) needs a newer
image, or one you build from this repository (in a container). The image reads files and
MongoDB but has no drivers for SQL servers, so a PostgreSQL or MySQL database needs an image built with that extra.
What this covers. An agent, or a script it writes, in that container can't read the data, because it isn't there. That holds whatever the agent tries, including a command the guard would not have recognised.
What it doesn't.
- You still run its code on the real data yourself, outside the agent container (
datanyx run -- python report.py, or your own environment), and then read what it prints before anything goes back. Putting that step inside the agent's container would bring the data back in. - The token is shared with the agent, which is what lets it use the server. The server is limited to what the tools return, which are the limits listed here and in the privacy model.
- Field names are still shown, and text anonymization can still miss things.
- Put TLS in front of the server if the two containers aren't on the same host (a server a team shares).
As an MCP server¶
The server speaks over stdio to one local agent. To host it for a team over HTTP with a bearer token, see Installing and deploying.
datanyx mcp --root ./exports # stdio; needs the `mcp` extra
Add it to your agent's MCP configuration:
{
"mcpServers": {
"datanyx": {
"command": "datanyx",
"args": ["mcp", "--root", "./exports"]
}
}
}
The agent gets six tools:
| Tool | What it returns |
|---|---|
describe_data |
A schema for a file, folder or env:NAME database, as text (the default), json-schema or summary |
synthetic_sample |
Fake rows that match it, as JSON Lines: 20 by default, at most 200. messy adds the flaws real data has |
check_code |
Findings for its SQL or pandas code against that schema, as datanyx check gives them |
scan_folder |
Which files hold personal data or secrets, by kind and count |
schema_diff |
What changed between two schemas, and what could break |
anonymize_file |
A UTF-8 text file with placeholders in place of names, identifiers and credentials |
Every tool describes the data the way datanyx schema does in that folder: the [schema] settings of
datanyx.toml (names to keep, map paths, hints, public columns, views, max_rows) apply, along with the
options the server was started with. The agent can add map paths, which only hide more, and nothing else.
It's limited by design:
- It can only read under
--root(default: the current folder), and database URLs are refused unless you start the server with--allow-urls, which also lets the agent name the URL of a file (https://,s3://, ...) for the server to fetch; leave it off if the server can reach things the agent shouldn't. For a database, put its URL in an environment variable and name that variable:datanyx mcp --allow-env DATABASE_URL, and the agent can then useenv:DATABASE_URL. No other variable can be used, and one that holds a path or asqlite:///URL stays limited to--root, as does asqlite:///URL under--allow-urls. anonymize_filealso hides credentials, and refuses files that exist to hold them or real values, such as.env,*.key,*.pem,id_rsa,.netrc, mapping files anddatanyx.local.toml. It reads up to 5 MB.describe_datareturns at most 200 tables at once (--max-tables Nchanges it), and says how many were left out. The agent can narrow it withtablesandexclude(glob patterns, which only ever match names it may see) andlimit, or ask forformat="summary", one line per table with no cap.--viewslets it see database views.check_codeandschema_diffalways use every table.- There's no
keeporhideoption, because either one tests whether a name exists. Choose--keep-entityand the terms to hide when you start the server instead. scan_folderuses the custom detectors and packs the server was started with, andexclude,max_sizeandinclude_examplesfrom[scan]. It doesn't run the name model.- There's no restore tool and no mapping, since both hold the real values.
- Errors are fixed messages, never the library's own text.
An audit log. --audit-log FILE (or audit_log under [mcp]) appends one line per tool call:
datanyx mcp --root ./data --audit-log audit.jsonl
datanyx audit audit.jsonl --since 2025-01-31 # who asked about what, and what was refused
$ datanyx audit audit.jsonl
42 calls in 3 sessions, 2025-01-31T09:12:03+00:00 to 2025-02-02T16:40:51+00:00
By tool: describe_data 20 · check_code 15 · scan_folder 5 · synthetic_sample 2
Paths asked about:
data/customers.csv ×27
../secrets ×2
2 calls failed or were refused:
describe_data: that path is outside the folders this server may read ×2
Each record has the time, a session id, the tool, the paths and settings it was called with, whether it worked, and sizes. It never has a value or anything the agent was given back: the SQL an agent asked to have checked is recorded as a length, and credentials in a database URL are replaced. The file is readable by its owner only. Keep it where the agent can't change it.
When something breaks. The agent is only told internal failure (ValueError), because an exception's text can
quote the data. For you, --debug-log FILE (or debug_log under [mcp]) records where each unexpected failure
happened, one line per failure:
{"time": "2025-02-02T16:40:51+00:00", "tool": "describe_data", "error": "ValueError", "causes": ["KeyError"],
"frames": [{"file": "datanyx/sources/json_source.py", "line": 70, "function": "extract"}, ...]}
That is the exception types, and for each frame the file, line and function name: never a message, a line of source, an argument or a variable, which are the places a value could be. The file is readable by its owner only, is never sent to the agent, and a refusal the agent was told about (a path outside the roots, say) isn't a bug and isn't logged. Keep it where the agent can't read it.
Huge files. --max-rows N limits how many rows of a data file are read, so one very large CSV can't keep
the server busy for minutes. Files that were cut short say so and give no size hint or key guesses; see
Huge files. The agent can't change it.
The server doesn't stop the agent from opening the files itself. Block that in its permissions, as above.