Run workflows on a managed sandbox provider

Run a workflow’s code changes in sandboxes from your own provider account, such as E2B, Daytona, Modal or Vercel

A workflow’s repository agent can run its commands in sandboxes from a managed sandbox provider you already pay for, instead of a Kubernetes cluster. Each code change gets a fresh sandbox in your provider account, and the sandbox is deleted when the change ends.

This uses the same dispatcher as running workflows in your environment. Only where each sandbox runs changes.

	Your Kubernetes cluster	A managed sandbox provider
Where commands run	A Job in your cluster	A sandbox in your provider account
Sandbox image	Any pod template you write	The provider’s default image, or a template you build there
Network rules	Kubernetes NetworkPolicy	The provider’s own network settings
Where the dispatcher runs	In the cluster	Anywhere that runs a container

Supported providers

Choose a provider to find its configuration value and credential variables. Set those variables in the dispatcher’s environment. CostGraph tests each provider live. Contact your account team before relying on one in production.

A–C

Agentuity

Set provider to agentuity and supply the following variables.

• AGENTUITY_SDK_KEY

Beam

Set provider to beam and supply the following variables.

• BEAM_TOKEN
• BEAM_WORKSPACE_ID

Blaxel

Set provider to blaxel and supply the following variables.

• BL_API_KEY
• BL_WORKSPACE

Brezel

Set provider to brezel and supply the following variables.

• BREZEL_API_KEY
• BREZEL_API_URL
• BREZEL_PROJECT_ID

Buddy

Set provider to buddy and supply the following variables.

• BUDDY_TOKEN
• BUDDY_WORKSPACE
• BUDDY_PROJECT

Cloudflare

Set provider to cloudflare and supply the following variables.

• CLOUDFLARE_SANDBOX_URL
• CLOUDFLARE_SANDBOX_API_KEY

Deploy a sandbox gateway in your account first. Point CLOUDFLARE_SANDBOX_URL at that gateway.

CodeSandbox

Set provider to codesandbox and supply the following variables.

• CSB_API_KEY

Collimate

Set provider to collimate and supply the following variables.

• COLLIMATE_API_KEY

CreateOS

Set provider to createos-sandbox and supply the following variables.

• CREATEOS_SANDBOX_API_KEY

D–L

Daytona

Set provider to daytona and supply the following variables.

• DAYTONA_API_KEY

Declaw

Set provider to declaw and supply the following variables.

• DECLAW_API_KEY

E2B

Set provider to e2b and supply the following variables.

• E2B_API_KEY

Freestyle

Set provider to freestyle and supply the following variables.

• FREESTYLE_API_KEY

givemeanode

Set provider to givemeanode and supply the following variables.

• GMN_TOKEN

Google Cloud Run

Set provider to cloud-run and supply the following variables.

• CLOUD_RUN_SANDBOX_URL
• CLOUD_RUN_SANDBOX_SECRET

Deploy a sandbox gateway in your account first. Point CLOUD_RUN_SANDBOX_URL at that gateway.

GravixLayer

Set provider to gravixlayer and supply the following variables.

• GRAVIXLAYER_API_KEY

HopX

Set provider to hopx and supply the following variables.

• HOPX_API_KEY

Isorun

Set provider to isorun and supply the following variables.

• ISORUN_API_KEY

Leap0

Set provider to leap0 and supply the following variables.

• LEAP0_API_KEY

Lelantos

Set provider to lelantos and supply the following variables.

• Either LELANTOS_API_KEY or E2B_API_KEY

Lightning AI

Set provider to lightning and supply the following variables.

• Either LIGHTNING_SANDBOX_API_KEY or LIGHTNING_API_KEY

M–R

MIOSA

Set provider to miosa and supply the following variables.

• MIOSA_API_KEY

Microsandbox

Set provider to microsandbox and supply the following variables.

• MSB_API_KEY
• MSB_API_URL only for a self-hosted control plane

Sandboxes use buildpack-deps:bookworm-scm by default. Set providerTemplate to use another image.

Modal

Set provider to modal and supply the following variables.

• MODAL_TOKEN_ID
• MODAL_TOKEN_SECRET

Mosaic

Set provider to mosaic and supply the following variables.

• MOSAIC_API_TOKEN

NeevCloud

Set provider to neevcloud and supply the following variables.

• NEEV_API_KEY
• NEEV_ORG_ID
• NEEV_PROJECT_ID

Northflank

Set provider to northflank and supply the following variables.

• NORTHFLANK_API_TOKEN
• NORTHFLANK_PROJECT_ID

Novita

Set provider to novita and supply the following variables.

• NOVITA_API_KEY

OpenComputer

Set provider to opencomputer and supply the following variables.

• OPENCOMPUTER_API_KEY

Quilt

Set provider to quilt and supply the following variables.

• QUILT_BASE_URL
• Either QUILT_API_KEY or QUILT_ACCESS_TOKEN

Railway

Set provider to railway and supply the following variables.

• RAILWAY_API_TOKEN

Run Cloud

Set provider to run-cloud and supply the following variables.

• Either RUN_CLOUD_API_KEY or RUN_CLOUD_API_TOKEN

Runloop

Set provider to runloop and supply the following variables.

• RUNLOOP_API_KEY

Runtime

Set provider to runtime and supply the following variables.

• RUNTIME_API_KEY

S–Z

Sandbox0

Set provider to sandbox0 and supply the following variables.

• Either SANDBOX0_TOKEN or SANDBOX0_API_KEY

Sprites

Set provider to sprites and supply the following variables.

• SPRITES_TOKEN

Superserve

Set provider to superserve and supply the following variables.

• SUPERSERVE_API_KEY

Tenki Cloud

Set provider to tenki and supply the following variables.

• Either TENKI_API_KEY or TENKI_AUTH_TOKEN

Tensorlake

Set provider to tensorlake and supply the following variables.

• TENSORLAKE_API_KEY

Upstash Box

Set provider to upstash and supply the following variables.

• UPSTASH_BOX_API_KEY

Vercel

Set provider to vercel and supply the following variables.

• VERCEL_TOKEN
• VERCEL_TEAM_ID
• VERCEL_PROJECT_ID

Give the dispatcher its own provider key, limited to creating and deleting sandboxes. Keep it separate from any key you connect to CostGraph for cost data.

Before you begin

• A CostGraph API key with the deployment:register and sandbox:worker scopes. The first pulls the dispatcher image from registry.costgraph.ai, the second lets the dispatcher take code changes.
• Credentials for one account listed in Supported providers.
• Somewhere to run one container that can reach agent-relay.costgraph.ai and your provider’s API over port 443.

Connect

Kubernetes

Store the provider credentials in a Secret whose keys are the variable names, then install the chart with your provider:

kubectl -n costgraph-agents create secret generic sandbox-provider \
  --from-literal=E2B_API_KEY="$E2B_API_KEY"

dispatcher:
  workerName: prod-e2b
  existingSecret: costgraph-sandbox-key
  imagePullSecrets:
    - name: costgraph-registry
  sandbox:
    provider: e2b
    providerSecret: sandbox-provider

Create costgraph-sandbox-key and costgraph-registry as described in Install. With a managed sandbox provider the dispatcher needs no permissions in the cluster.

Docker

Sign in to the registry with your CostGraph API key. Then run the dispatcher with the key in a file and the provider credentials in its environment:

docker login registry.costgraph.ai -u x
printf '%s' "$COSTGRAPH_API_KEY" > ./api-key
docker run -d --restart unless-stopped \
  -v "$PWD/api-key:/run/costgraph/api-key:ro" \
  -e RELAY_URL=https://agent-relay.costgraph.ai \
  -e RELAY_API_KEY_FILE=/run/costgraph/api-key \
  -e WORKER_NAME=prod-e2b \
  -e SANDBOX_PROVIDER=e2b \
  -e E2B_API_KEY \
  registry.costgraph.ai/costgraph-sandbox:v2.1.0

WORKER_NAME names this dispatcher in CostGraph: lowercase letters, digits and hyphens, up to 63 characters. After it connects, it is available in a goal’s Sandbox setting. See Choose where a goal runs.

Sandbox image

By default each sandbox starts from the provider’s default image, and the dispatcher installs the agent into it before the code change starts. The image must have curl, sha256sum, base64 and git, and either run as root or allow sudo. The install adds a few seconds to every code change.

To skip the install and add your own tools, build a template in your provider. It must already contain the agent and our two scripts. Then name it:

dispatcher:
  sandbox:
    providerTemplate: costgraph-worker

Build the template from our worker image, registry.costgraph.ai/costgraph-sandbox-worker, with your provider’s own template tooling. The requirements are the same as for your own sandbox image.

Network

Each provider controls egress in its own settings. The sandbox must reach agent-relay.costgraph.ai and github.com on port 443. Everything else is your choice.

Lifetime and cost

A code change that runs longer than dispatcher.sandbox.ttlSeconds (two hours by default) is stopped, and the provider removes its sandbox. Sandbox time is billed by your provider to your account.

If the dispatcher stops while a code change is running, that sandbox keeps running until the change ends or the timeout removes it.