What it is
Your DataNivra agent already keeps production rows inside your network. Isolated execution adds an operating-system boundary inside the agent host: every stage that reads or transforms rows — discovery profiling and classification, subsetting, masking, synthesis, validation and provisioning — runs in its own fresh, short-lived worker instead of the agent process.
A worker sees only what its stage needs:
- the stage's input (read-only) and its output directory;
- this job's own connection details, for the stages that read a source or write a target;
- the pseudonymization keys this job's masking policy names, at the versions it names, one request at a time.
It never sees the agent's identity key, its control-plane token, your secret store, other jobs, the container runtime, or — for stages that need no source or target — any network.
The agent stays in charge of everything else: leases, checkpoints, certification, publication and reporting work exactly as before, and published data is byte-for-byte the same as without isolation.
Choose a level
| Level | Backend | Availability | How it isolates | Needs on the agent host |
|---|---|---|---|---|
| Standard (default) | — | available | the agent process, as today | nothing |
| Container | OCI (Docker or Podman) | generally available | fresh container per stage: no capabilities, read-only root, default seccomp profile, no privilege escalation, bounded memory, CPU and processes, no network unless the stage needs a source or target | Linux with Docker ≥ 24 or Podman ≥ 4, preferably rootless |
| Kernel boundary | gVisor | generally available | as Container, and the stage's system calls are answered by gVisor's user-space kernel | runsc registered with Docker |
| Kernel boundary | Firecracker | generally available (agent 0.6.1+, with the jailer) | each stage in its own microVM with its own guest kernel and no network device, run under Firecracker's jailer | Linux with KVM (/dev/kvm) |
gVisor and Firecracker both keep a stage's system calls away from the host kernel, by different means; if your policy needs one specifically, name it.
Turn it on for an agent
# on the agent host, after pulling the agent image by digest
export DATANIVRA_AGENT_ISOLATION_BACKEND=OCI # or GVISOR, FIRECRACKER
export DATANIVRA_AGENT_ISOLATION_IMAGE=ghcr.io/manuelbomi/datanivra-agent@sha256:<digest>
export DATANIVRA_AGENT_ISOLATION_SOURCE_NETWORK=dn-sources # only if stages read network sources
datanivra-agent isolation doctor # every check must passRestart the agent. While its runtime check passes, it advertises the backend to the control plane; datanivra-agent isolation status shows recent stage outcomes, start-up times and any running workers.
Run it in your own environment
Isolation runs entirely on your agent host. There is nothing extra to download from DataNivra: the backends are built into the agent (0.6.0 or later) and the worker is the same signed agent image. You install the sandbox runtime from its own project and keep it patched like any other system package.
Where it is supported
| Agent deployment | Container (OCI) | gVisor | Firecracker |
|---|---|---|---|
| Linux server or VM with Docker ≥ 24 or Podman ≥ 4 (recommended) | yes | yes, with runsc registered | yes, with /dev/kvm |
| Kubernetes (Helm chart) | — | whole agent pod under a sandboxed runtime (runtimeClassName, for example GKE Sandbox) | — |
| Docker Compose or a containerized agent | only with a rootless runtime socket mounted for the agent | same | — |
| AWS ECS Fargate, Azure Container Apps | — | — | — |
| Windows, macOS, WSL2 | development only | development only | development only |
Verified on a stock Ubuntu 24.04 LTS server (Canonical kernel 6.8, AppArmor on) with Ubuntu's Docker Engine: the isolation test suites, the isolation doctor checks, and real discovery jobs sent by the hosted control plane to an agent running Container, gVisor and Firecracker in turn — Firecracker under its jailer, with an agent user whose only elevated right is the launcher.
Step by step on a Linux server
- Install the runtime for the level you want: - Container: Docker Engine ≥ 24 (your distribution's package or Docker's repository) or Podman ≥ 4. A rootless runtime for a dedicated agent user is preferred. - gVisor: Docker as above, then
runscfrom gVisor's apt repository andsudo runsc install && sudo systemctl restart dockerto register it. - Firecracker (agent 0.6.1 or later): the Firecracker and jailer release binaries, a guest kernel you build from kernel.org sources with Firecracker's guest configuration, and the worker root filesystem built from the agent image. Then runinstall-jailer.sh(shipped in the agent image under/opt/datanivra/firecracker-launcher/) once as root: it installs a small launcher the agent may run through a singlesudorule, so each microVM runs under Firecracker's jailer — in a chroot, as a dedicated user, with cgroup limits — while the agent itself never runs as root. SetDATANIVRA_AGENT_ISOLATION_FIRECRACKER_LAUNCHER=/usr/local/libexec/datanivra-firecracker-launch. - Run the agent as an ordinary user that may use the runtime (for example in the
dockergroup, or a rootless runtime of its own). The agent refuses to drive a runtime as root. - Pull and verify the agent image by digest with cosign v3 or later (see Download the agent).
- Point the agent at it with the settings shown under Turn it on for an agent. Stages that read a database also need
DATANIVRA_AGENT_ISOLATION_SOURCE_NETWORK: a Docker network that reaches only your source systems. - Check it:
datanivra-agent isolation doctormust pass every check (for gVisor and Firecracker it includeskernel_boundary_observed; with the jailer alsojailer_launcher_ready). Then restart the agent; it advertises the backend to the control plane. - Optionally require it for your organization (next section).
To confirm gVisor by hand: docker run --rm --runtime runsc --entrypoint python <agent image> -c 'import platform; print(platform.release())' prints a release ending in -gvisor.
Plan for
- What stays in the agent process. Short connector calls that prove a source is read-only, check its health or read its structure stay in the agent and return metadata only. Compliance-guard scans and document-set builds are not offered by isolated agents (see Good to know).
- Source credentials. A stage that reads a source holds that job's read-only credentials and can reach the source network you give it, so keep that network limited to the source systems and keep source accounts read-only (DataNivra checks this before every job).
- The runtime belongs to the agent. Whoever controls the agent's user controls its container runtime. Give the agent a dedicated user and, where possible, a rootless runtime; never the host's root Docker socket.
- Container shares the host kernel. Keep the kernel and container runtime patched. If your policy calls for a separate kernel per stage, choose gVisor (or Firecracker) and set the minimum to Kernel boundary.
- gVisor specifics. The process limit does not cap threads inside the sandbox (the memory and CPU limits still apply), and a few native database drivers use system calls gVisor does not implement; such a stage fails with
ISOLATED_WORKER_CRASHEDinstead of running, so use Container for that source. - Workspace size. Give the agent's workspace enough disk and keep the workspace quota settings (
DATANIVRA_AGENT_WORKSPACE_QUOTA_BYTES,_ENTRIES); for a hard limit put the workspace on a volume with per-project quotas. - Start-up time. Each isolated stage starts a fresh worker, about two seconds per stage.
- Firecracker specifics. The launcher that starts each microVM under the jailer runs as root, so install it only from the agent image and keep it, its configuration and the Firecracker files root-owned (the installer does this). A microVM has no network: Firecracker serves file sources and directory targets. Each stage's inputs are copied onto its own drive, so give the workspace room for one copy per running stage.
Require it for your organization
Organization administrators set a minimum in Organization → Execution isolation, with the CLI (datanivra org isolation-update --min-isolation CONTAINER), or through the API (PATCH /v1/organization/execution-isolation). Every change is audited.
- Jobs are sent only to agents whose isolation meets the minimum; any other agent never receives them, and the job reports
AGENT_ISOLATION_UNSUPPORTED. - Requests from the console, API, SDKs, CLI (
--min-isolation), MCP clients and CI pipelines can ask for more isolation, never less. - The requirement travels inside the signed job command, and the agent checks it again before it opens a source. A job is never run with weaker isolation than required.
Good to know
- Availability. Container (OCI), gVisor and Firecracker are generally available (Firecracker from agent 0.6.1, run under its jailer). Isolation is opt-in: Standard stays the default for every installation.
- Start-up cost. Each isolated stage starts a fresh worker, which adds about two seconds per stage; row processing itself runs at the usual speed.
- Where it runs. Per-stage isolation needs a Linux host with a container runtime (or KVM for Firecracker). On Kubernetes you can run the whole agent pod under a sandboxed runtime instead (
runtimeClassName, for example GKE Sandbox). - Firecracker microVMs have no network: use it with file sources and directory targets; use OCI or gVisor for network sources and targets.
- Compliance-guard scans and document-set builds keep running in the agent process for now, so an agent with an isolation backend does not offer them, and they are refused whenever an isolation minimum applies — never run unisolated. Run them on an agent with the Standard backend.
Every isolation code (ISOLATION_*, ISOLATED_*) has an entry with its fix in the support center.