Configuring Sandboxes

---

This page covers environment variables and secrets, volumes, scratch space in /tmp, and resource detection for sandboxes. Resources, workload identity, tags, and tracing apply to sandboxes, functions, and scaling groups, and each has its own page:

• Resources and GPUs
• Workload Identity
• Tags
• Tracing Policy

---

​

Environment variables and secrets

Pass plaintext configuration through env or resolve credentials through Chalk-managed Secret values:

from chalkcompute import Image, Sandbox, Secret

sandbox = Sandbox(
    image=Image.debian_slim("3.12"),
    name="api-client",
    env={"LOG_LEVEL": "INFO"},
    secrets=[
        Secret.from_chalk_env("OPENAI_API_KEY"),
        Secret.from_chalk_integration("prod_postgres"),
    ],
).run()

Secrets are resolved at creation time and exposed to the sandbox as environment variables. See Secrets for the available Secret constructors.

​

Mounting volumes

Attach a Volume to share durable state between runs or expose a large dataset without baking it into the image:

from chalkcompute import Image, Sandbox, Volume

vol = Volume("training-data")
vol.put_file("inputs/example.txt", b"hello\n")

sandbox = Sandbox(
    image=Image.debian_slim("3.12"),
    name="volume-reader",
    volumes=[("training-data", "/data")],
).run()

result = sandbox.exec("cat", "/data/inputs/example.txt")
print(result.stdout_text)  # "hello\n"

sandbox.terminate()

Mounted volumes persist across sandbox lifecycles and can be shared by other sandboxes that mount the same volume.

​

Scratch space in /tmp

On the host compute class, /tmp is an in-memory filesystem. Files you write there count toward the sandbox’s memory limit, and /tmp has no size limit of its own. When the sandbox’s memory use, including files in /tmp, reaches the limit, the sandbox may be terminated with an out-of-memory error.

The in-memory /tmp suits small temporary files and workloads that need fast reads and writes. To keep larger files in /tmp, set memory high enough to cover both your processes and the files you write there.

To use disk for /tmp instead, mount an empty directory there. With the CLI, pass --empty-dir /tmp to chalk sandbox create. The directory holds up to 2GiB by default, and a size after = raises the limit:

chalk sandbox create -i python:3.12 -n scratch-disk --empty-dir /tmp=10Gi

---

​

Resource detection

A sandbox can record resources it creates by inspecting its egress traffic. The GITHUB_PULL_REQUESTS detector inspects requests to api.github.com and records each pull request the sandbox opens, with the pull request URL as the resource ID. Detection is off by default, and works only on the host compute class.

import chalkcompute

sandbox = chalkcompute.Sandbox(
    image=chalkcompute.Image.debian_slim(),
    resource_detectors=[chalkcompute.ResourceDetector.GITHUB_PULL_REQUESTS],
).run()

The SDK adds api.github.com to the sandbox’s network policy. If the sandbox has no network_policy, this creates one that allows only that host.

With the CLI, pass --resource-detection github-pull-requests to chalk sandbox create:

chalk sandbox create -i python:3.12 -n pr-bot \
  --host api.github.com \
  --resource-detection github-pull-requests