Agent Sandbox

The Agent Sandbox is where Noxus runs code it did not write: Run Code nodes and all plugin execution. It is a separate service with its own isolation model, and it is not deployed by default.

Plugins require the sandbox. The plugin system is switched on by the presence of SANDBOX_MANAGER_URL, which is only injected into the Noxus Backend and Workers when the sandbox is deployed. Without it, plugin nodes and triggers do not load — and nothing raises an error. They are simply absent from the platform.If you are upgrading from a release that ran a standalone plugin server, you must enable the sandbox or you will lose your plugins.

When you need it

You need it

You use plugins, or your workflows contain Run Code nodes that should be properly isolated.

You may not need it

No plugins and no Run Code nodes. The rest of the platform is unaffected by leaving it off.

Isolation modes

The sandbox runs jailed processes. Which jail it can use depends on what your platform lets a container request.

Mode	Isolation	Requires	Use when
`syd`	Syscall filtering and network jail	`SYS_PTRACE`	Default. Any deployment running untrusted or user-authored code.
`minimal`	`chroot` plus egress restricted by NetworkPolicy	`SYS_ADMIN`	Only when the platform refuses `SYS_PTRACE`, and only for code you trust.

minimal constrains the filesystem and the network but not syscalls. It is meaningfully weaker than syd. Treat it as a compatibility fallback, not an equivalent option.

Platform compatibility

Platform	`syd` jail	Notes
EKS	Supported	Works on Auto Mode and managed node groups.
GKE Standard	Supported
GKE Autopilot	Not supported	Autopilot refuses `SYS_PTRACE`. You must use `minimal`, or move to Standard node pools.
AKS	Supported
Restrictive PodSecurity admission	Depends	A policy that blocks added capabilities blocks `syd`.

The network jail in minimal mode is enforced by a Kubernetes NetworkPolicy, which requires a CNI that implements policy. The azure-aks stack in noxus-infra sets network_policy = "cilium" for this reason; the default CNIs on EKS and GKE already enforce policy. Without an enforcing CNI the NetworkPolicy object exists and does nothing.

Configuration

Variable	Default	Description
`SANDBOX_MANAGER_URL`	`""`	URL of the sandbox manager. Empty disables the sandbox and the entire plugin system.
`USE_REMOTE_SANDBOX`	`true`	Route Run Code through the sandbox service rather than executing locally.
`REMOTE_SANDBOX_BACKEND`	`""`	Remote execution backend. `syd` in normal use.
`SANDBOX_BACKEND`	`syd`	Jail implementation.
`LOCAL_SANDBOX_BACKEND`	`deno`	Worker-local fallback — see below.
`PLUGIN_CALL_TIMEOUT`	`240.0`	Seconds before a plugin call is abandoned.

The local fallback matters

LOCAL_SANDBOX_BACKEND is what a Worker uses when the remote sandbox is off or unhealthy:

none — no local execution. The safest setting when a remote sandbox is present, and the default the Helm chart selects when sandbox.enabled=true.
deno — a worker-local Deno/Pyodide runtime. Reasonable isolation, limited capability.
subprocess — runs user code as a plain subprocess in the Worker’s own process tree. Much weaker isolation. Do not use this in a multi-tenant deployment.

Setting LOCAL_SANDBOX_BACKEND=subprocess as a way to “make Run Code work without deploying the sandbox” gives untrusted code the Worker’s filesystem, network, and environment — including its database credentials.

Deployment

Kubernetes
Serverless containers
Virtual Machine

The sandbox is a Deployment in the Noxus Helm chart, off by default:

sandbox:
  enabled: true
  jail: syd          # or "minimal" where SYS_PTRACE is unavailable
  localBackend: ""   # empty selects the per-mode default ("none" when enabled)
  storage: "10Gi"
  shmSize: "512Mi"
  resources:
    requests: { cpu: "1", memory: "2Gi" }
    limits: { cpu: "2", memory: "4Gi" }

Enabling it also injects SANDBOX_MANAGER_URL into the Backend and Workers, and applies the sandbox NetworkPolicy.In the Terraform stacks the equivalent is sandbox_enabled = true, which is the default there.

Deploy the sandbox as an additional internal container service, reachable only from the Backend and Workers — it should not have public ingress.Point SANDBOX_MANAGER_URL at its internal address.

Syscall-level jailing depends on capabilities that managed container runtimes may not grant. Verify that your platform permits the sandbox’s required capabilities before relying on syd isolation here.

The appliance image runs the sandbox as a Compose service (agentsandbox) and sets SANDBOX_MANAGER_URL=http://agentsandbox:8000 automatically. No additional configuration is needed.

Filesystem and state

The sandbox uses a copy-on-write filesystem whose state is periodically synced to object storage, so the pod itself can run on ephemeral disk.

Variable	Default	Description
`SANDBOX_FS_ENABLED`	`"true"`	Enable the synced copy-on-write filesystem.
`SANDBOX_FS_PREFIX`	`"sandboxes"`	Key prefix within the storage bucket.
`SANDBOX_FS_SYNC_INTERVAL`	`"300"`	Seconds between syncs.

It reuses the platform’s existing storage configuration — BUCKET_CLIENT, SPOTFLOW_STORAGE_BUCKET, and whatever credentials or workload identity the Backend and Workers already use. No separate bucket is required.

Sizing

The sandbox’s own resource requests cover the manager, not the code it runs. Jailed processes draw from the same container limits, so a deployment running heavy Run Code workloads needs headroom above the defaults. Start at 1 vCPU / 2 GiB requests with 2 vCPU / 4 GiB limits, and raise the limits if you see sandbox restarts under load.

Health and troubleshooting

The sandbox manager exposes /health, used for all three probes.

Symptom	Cause
Plugins missing from the platform, no error anywhere	Sandbox not deployed, so `SANDBOX_MANAGER_URL` is empty
Sandbox pods stuck `Pending` or failing admission	`SYS_PTRACE` refused — GKE Autopilot or a restrictive PodSecurity policy. Use `minimal`.
Run Code executes but has no network access	Expected. The NetworkPolicy restricts egress by design; widen it deliberately rather than disabling the sandbox.
Sandbox restarts during heavy Run Code use	Container limits exhausted by the jailed processes. Raise them.

Plugin Development

Build plugins that run inside the sandbox.

Environment Configuration

The full platform variable reference.

Overview

Deployment Options

Networking

Configuration

Security

Operations

When you need it

You need it

You may not need it

Isolation modes

Platform compatibility

Configuration

The local fallback matters

Deployment

Filesystem and state

Sizing

Health and troubleshooting

Plugin Development

Environment Configuration

​When you need it

You need it

You may not need it

​Isolation modes

​Platform compatibility

​Configuration

​The local fallback matters

​Deployment

​Filesystem and state

​Sizing

​Health and troubleshooting

Plugin Development

Environment Configuration

When you need it

Isolation modes

Platform compatibility

Configuration

The local fallback matters

Deployment

Filesystem and state

Sizing

Health and troubleshooting