Documentation

Isolated execution: OCI, gVisor & Firecracker

Run test data management work in an isolated sandbox on your own servers — every row-level stage of your agent's jobs in a fresh, hardened container (OCI), a gVisor sandbox or a Firecracker microVM — all generally available — and let your organization require it.

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

LevelBackendAvailabilityHow it isolatesNeeds on the agent host
Standard (default)—availablethe agent process, as todaynothing
ContainerOCI (Docker or Podman)generally availablefresh 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 targetLinux with Docker ≥ 24 or Podman ≥ 4, preferably rootless
Kernel boundarygVisorgenerally availableas Container, and the stage's system calls are answered by gVisor's user-space kernelrunsc registered with Docker
Kernel boundaryFirecrackergenerally 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 jailerLinux 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 pass

Restart 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 deploymentContainer (OCI)gVisorFirecracker
Linux server or VM with Docker ≥ 24 or Podman ≥ 4 (recommended)yesyes, with runsc registeredyes, with /dev/kvm
Kubernetes (Helm chart)—whole agent pod under a sandboxed runtime (runtimeClassName, for example GKE Sandbox)—
Docker Compose or a containerized agentonly with a rootless runtime socket mounted for the agentsame—
AWS ECS Fargate, Azure Container Apps———
Windows, macOS, WSL2development onlydevelopment onlydevelopment 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

  1. 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 runsc from gVisor's apt repository and sudo runsc install && sudo systemctl restart docker to 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 run install-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 single sudo rule, 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. Set DATANIVRA_AGENT_ISOLATION_FIRECRACKER_LAUNCHER=/usr/local/libexec/datanivra-firecracker-launch.
  2. Run the agent as an ordinary user that may use the runtime (for example in the docker group, or a rootless runtime of its own). The agent refuses to drive a runtime as root.
  3. Pull and verify the agent image by digest with cosign v3 or later (see Download the agent).
  4. 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.
  5. Check it: datanivra-agent isolation doctor must pass every check (for gVisor and Firecracker it includes kernel_boundary_observed; with the jailer also jailer_launcher_ready). Then restart the agent; it advertises the backend to the control plane.
  6. 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_CRASHED instead 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.

← All documentation