Skip to content

Using it with an agent

  1. Run DataNyx yourself, and read the schema before sharing it.
  2. 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 protect sets this up for Claude Code.
  3. 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 (or settings.local.json with --local): deny rules for Read and Edit on the paths, plus a PreToolUse guard hook. Anything already in the file is kept.
  • .mcp.json: a datanyx MCP server limited to those paths (--no-mcp skips 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 **/*.py is 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 -c and eval don't hide a path.
  • Git commands that would print the data: git show HEAD:data/x.csv and git grep, and git diff, git show or git log -p when 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-search allows those.
  • Changes to the protected data and to what sets the protection up: .claude, .datanyx, .mcp.json, a datanyx.toml in 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:

  • run is 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, init and protect are 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-config and the DATANYX_CONFIG variable.
  • --names-from can only name the protected data, and no output option can point at it.
  • The agent can't edit datanyx.toml or datanyx.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 datanyx container 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 agent container 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 use env:DATABASE_URL. No other variable can be used, and one that holds a path or a sqlite:/// URL stays limited to --root, as does a sqlite:/// URL under --allow-urls.
  • anonymize_file also hides credentials, and refuses files that exist to hold them or real values, such as .env, *.key, *.pem, id_rsa, .netrc, mapping files and datanyx.local.toml. It reads up to 5 MB.
  • describe_data returns at most 200 tables at once (--max-tables N changes it), and says how many were left out. The agent can narrow it with tables and exclude (glob patterns, which only ever match names it may see) and limit, or ask for format="summary", one line per table with no cap. --views lets it see database views. check_code and schema_diff always use every table.
  • There's no keep or hide option, because either one tests whether a name exists. Choose --keep-entity and the terms to hide when you start the server instead.
  • scan_folder uses the custom detectors and packs the server was started with, and exclude, max_size and include_examples from [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.