Sandbox runtime

Choose between on-cluster OpenSandbox and E2B cloud sandboxes for self-hosted Dreadnode.

The sandbox runtime is chart configuration, applied by a redeploy. Configure it in a Helm overlay, under Sandbox Runtime in the Admin Console, or with matching KOTS ConfigValues items.

Commands on this page use $NAMESPACE. For Helm, set it to your release namespace. For Embedded Cluster, enter sudo ./dreadnode shell, then set it to kotsadm.

Dreadnode runs agent code in isolated sandboxes. Choose the runtime based on where workloads may execute and whether you need task-based evaluations.

Runtime	Workload location	Network requirement	Task evaluations
OpenSandbox	Your cluster	No public callback	Not supported
E2B	E2B cloud	Outbound access and public callbacks	Supported

Use OpenSandbox

OpenSandbox is the default and runs through the bundled sandbox controller and server:

dreadnode-api:
  config:
    sandboxProvider: opensandbox

apiVersion: kots.io/v1beta1
kind: ConfigValues
spec:
  values:
    sandbox_provider:
      value: opensandbox

No credential or callback configuration is required. OpenSandbox is the appropriate choice for air-gapped installs and environments where workload data cannot leave the cluster.

Trust a private CA in OpenSandbox

Build a customer runtime image that installs the organization’s public root certificate.

FROM docker.io/dreadnode/dreadnode:latest

USER root
COPY organization-root.crt /usr/local/share/ca-certificates/
RUN update-ca-certificates

USER user

update-ca-certificates adds the organization root to the image’s combined system bundle while retaining normal public roots. The image contains no private key. Build and publish it to a registry that the OpenSandbox nodes can pull:

docker build \
    -t registry.acme.internal/dreadnode/runtime-private-ca:v1 \
    .
docker push registry.acme.internal/dreadnode/runtime-private-ca:v1

Point the API at the published image:

dreadnode-api:
  config:
    dockerRuntimeImage: registry.acme.internal/dreadnode/runtime-private-ca:v1

apiVersion: kots.io/v1beta1
kind: ConfigValues
spec:
  values:
    advanced_helm_values:
      value: |
        dreadnode-api:
          config:
            dockerRuntimeImage: registry.acme.internal/dreadnode/runtime-private-ca:v1

The Dreadnode runtime’s platform API, model gateway, and trace exporter use the image’s OS trust store. No certificate-path environment variables are required.

CA rotation requires a new image build and tag, a chart upgrade, and recreation of affected runtime sandboxes. This recipe does not configure arbitrary task images, E2B templates, dynamic CA injection, or provider-mounted CA files. See Trust an internal certificate for the host TUI, CLI, and SDK setup.

Use E2B

E2B requires outbound access to api.e2b.dev and *.e2b.app. Create an API key in your E2B team and enable custom template builds for the account.

Configure E2B and its API key:

Store the API key in the Dreadnode namespace:

kubectl -n "$NAMESPACE" create secret generic e2b-credentials \
    --from-literal=E2B_API_KEY='<your-e2b-key>'

Then select E2B and reference the Secret:

dreadnode-api:
  config:
    sandboxProvider: e2b
    e2b:
      apiKey:
        existingSecret: e2b-credentials
        secretKey: E2B_API_KEY

dreadnode-sandbox-controller:
  enabled: false
dreadnode-sandbox-server:
  enabled: false

apiVersion: kots.io/v1beta1
kind: ConfigValues
spec:
  values:
    sandbox_provider:
      value: e2b
    e2b_api_key:
      valuePlaintext: '<your-e2b-key>'

The Embedded Cluster paths protect the key in stored configuration, then inject it as a plain environment variable on the API Deployment. Anyone who can read that Deployment can read the key. Use the Helm path with a pre-created Secret when that exposure is unacceptable. Disabling the on-cluster subcharts in Helm is optional, but reclaims their resources.

The API validates the E2B configuration at startup: it authenticates the key, checks the template aliases, logs any configuration errors, and gives up after five seconds so the API can finish starting. Check the API logs after switching providers:

kubectl -n "$NAMESPACE" logs deploy/dreadnode-api

Configure public callbacks

E2B sandboxes and the E2B control plane call back into Dreadnode for:

agent runtime reporting
model inference through LiteLLM, when enabled
lifecycle webhooks at /api/v1/webhooks/e2b

These URLs must be reachable from E2B’s cloud. The defaults use the configured Dreadnode domain and work only when that domain is publicly reachable. For an internal-only deployment, expose a restricted tunnel, bastion, or reverse proxy and configure both callback URLs:

dreadnode-api:
  config:
    e2b:
      serverUrl: https://dreadnode-bastion.example.com
    litellm:
      publicUrl: https://dreadnode-bastion.example.com/llm/v1

apiVersion: kots.io/v1beta1
kind: ConfigValues
spec:
  values:
    e2b_server_url:
      value: https://dreadnode-bastion.example.com
    litellm_public_url:
      value: https://dreadnode-bastion.example.com/llm/v1

Leave serverUrl empty when the configured Dreadnode domain is already reachable from E2B. The API registers the lifecycle webhook beneath the same URL; it has no separate setting.

Runtime limits

Evaluations without an explicit task timeout run for up to one hour by default. Explicit timeouts can run for up to the configured maximum, which defaults to eight hours:

dreadnode-api:
  config:
    sandboxRuntime:
      defaultRuntimeSeconds: 3600
      maxRuntimeSeconds: 28800

apiVersion: kots.io/v1beta1
kind: ConfigValues
spec:
  values:
    sandbox_limits_customize:
      value: "1"
    sandbox_default_runtime_seconds:
      value: "3600"
    sandbox_max_runtime_seconds:
      value: "28800"

Set the default to at least 60 seconds and no higher than the maximum. The API rejects an invalid pair at startup. These values apply to both providers. E2B also enforces your account’s session limit. Raise the default if long unattended evaluations are being cut short.

Template aliases

Dreadnode extends published base templates for task and interactive runtime sandboxes:

dreadnode-api:
  config:
    e2b:
      taskTemplateAlias: brian-3740/dn-task-prod
      runtimeTemplateAlias: brian-3740/dn-dreadnode-prod

apiVersion: kots.io/v1beta1
kind: ConfigValues
spec:
  values:
    e2b_task_template_alias:
      value: brian-3740/dn-task-prod
    e2b_runtime_template_alias:
      value: brian-3740/dn-dreadnode-prod

Override these aliases only when you maintain compatible forks of the base templates. The first evaluation for a task builds a team-local template and is slower than later runs, which reuse it. E2B bills runtime and template builds to your account, and Dreadnode does not automatically prune accumulated templates.