Configuring Sandboxes

---

This page covers environment variables and secrets, volumes, 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.

---

​

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