📦 Code Sandboxes

Code Sandboxes (code_sandboxes) is a Python package for running code in isolated sandbox variants through a unified API.

Canonical variant names:

cloudflare
coreweave
datalayer
daytona
docker
e2b
eval
google-colab
jupyter-server
kaggle
modal
monty

Documentation

The full documentation is the single source of truth:

Docs home: https://code-sandboxes.datalayer.tech
Providers and variant setup: https://code-sandboxes.datalayer.tech/providers
Installation: https://code-sandboxes.datalayer.tech/install
CLI usage: https://code-sandboxes.datalayer.tech/cli
API reference: https://code-sandboxes.datalayer.tech/api-reference
Examples: https://code-sandboxes.datalayer.tech/examples
Guide: https://code-sandboxes.datalayer.tech/guide

Published site:

https://code-sandboxes.datalayer.tech

Install

pip install code-sandboxes

For provider-specific extras and credentials, see https://code-sandboxes.datalayer.tech/install and https://code-sandboxes.datalayer.tech/providers.

Jupyter Server Sandbox

from code_sandboxes import Sandbox

# Option 1: manage a local Jupyter server automatically
with Sandbox.create(variant="jupyter-server") as sandbox:
  print(sandbox.run_code("1 + 1").text)  # 2

# Option 2: connect to an existing Jupyter server
with Sandbox.create(
  variant="jupyter-server",
  server_url="http://localhost:8888",
  token="MY_TOKEN",
) as sandbox:
  sandbox.run_code("x = 40")
  print(sandbox.run_code("x + 2").text)  # 42

Jupyter over Provider Ingress

Daytona, E2B, and Modal sandboxes can prepare a real Jupyter Server and return the provider HTTPS/WebSocket ingress needed to reach it:

from code_sandboxes import JupyterServerOptions, Sandbox

sandbox = Sandbox.create(variant="daytona")  # also: e2b, modal
sandbox.start()
endpoint = sandbox.prepare_jupyter_server(
    JupyterServerOptions(port=8888, install_if_missing=True)
)

Preparation first checks that jupyter-server and ipykernel are both importable, installs the pair if that check fails, launches Jupyter in the background, and waits for its port to accept connections. Calling the method again on the same sandbox returns the cached endpoint. Provider-ingress credentials are in endpoint.headers; the separate Jupyter token is in endpoint.query. Do not send either to the browser: a server-side gateway should apply them while proxying HTTP and WebSocket traffic.

install_if_missing=False makes a prebuilt template or snapshot mandatory. Templates and snapshots are the intended cold-start optimization; the conditional installation is the preliminary path for ordinary provider base images.

Kaggle Sandbox

Kaggle supports both batch execution and interactive connections through the kaggle sandbox. Install its optional dependency first:

pip install "code-sandboxes[kaggle]"

Required credentials for batch mode:

~/.kaggle/kaggle.json, or
KAGGLE_API_KEY

# Install Kaggle support
pip install code-sandboxes[kaggle]

# Optional: env-based credentials (if not using ~/.kaggle/kaggle.json)
export KAGGLE_API_KEY="<your-kaggle-api-key>"

# Launch the REPL
code-sandboxes repl --variant kaggle

For batch execution, configure Kaggle credentials and create the sandbox without a runtime URL:

from code_sandboxes import Sandbox

with Sandbox.create(variant="kaggle") as sandbox:
    result = sandbox.run_code("print('hello from kaggle')")
    print(result.stdout)

The lower-level batch API is also available directly:

from code_sandboxes import KaggleKernelExecutor

executor = KaggleKernelExecutor()
result = executor.execute(
    "print('hello from kaggle')",
    title="code-sandboxes-demo",
    accelerator="NvidiaTeslaT4",
    wait=True,
)
print(result.status, result.stdout)
print(result.to_kernel_reply())

For interactive execution, copy the WebSocket channels URL from an active Kaggle notebook session and pass it to the sandbox or client:

from code_sandboxes import KaggleKernelClient

with KaggleKernelClient.from_channels_url(channels_url, token=None) as kernel:
    print(kernel.execute("x = 1 + 1; print(x)"))

See the complete Kaggle guide for authentication, accelerators, channels URL retrieval, and execution options.

Google Colab

Google Colab exposes an already-running kernel through an authenticating proxy. Copy its WebSocket channels URL from the browser's Network tools, then pass it directly to the sandbox:

from code_sandboxes import Sandbox

with Sandbox.create(variant="google-colab", channels_url=channels_url) as sandbox:
    print(sandbox.run_code("x = 1 + 1; print(x)").stdout)

The lower-level client and parser are owned by Code Sandboxes as well:

from code_sandboxes import GoogleColabKernelClient, parse_google_colab_channels_url

server_url, kernel_id, proxy_token = parse_google_colab_channels_url(channels_url)
with GoogleColabKernelClient.from_channels_url(channels_url) as kernel:
    print(kernel.execute("print('hello from colab')"))

See the complete Google Colab guide for proxy authentication, explicit connection values, and channels URL retrieval.

Contents attachments

The Datalayer Contents service decides what a sandbox is given — a volume, a home folder, a dataset revision, a bucket — and writes it down as a manifest. The client honours it the same way on every provider, and answers honestly where a provider cannot:

from code_sandboxes import CodeSandboxClient, ContentAttachmentError, ContentManifest

manifest = ContentManifest.model_validate(contents_api.attachment_manifest(sandbox_uid))
client = CodeSandboxClient.create(variant="daytona")

print(client.content_capabilities())     # mount, bucket_mount, materialize, client, ...
try:
    prepared = client.attach(manifest)   # configure, start, install the manifest, prepare
except ContentAttachmentError as error:  # a REQUIRED attachment is not ready
    print(error.uid, error.code)         # e.g. "MOUNT_NEEDS_RESTART"; the sandbox keeps running

client.reconcile_contents(manifest)      # after a restart: re-check, repair, never duplicate
client.attachment_status("attachment-1")
client.detach("attachment-1")            # removes what was delivered, never the source

Inside the sandbox the manifest is /etc/datalayer/contents.json (or ~/.datalayer/contents.json when /etc cannot be written) and the environment names it: DATALAYER_CONTENTS_MANIFEST, DATALAYER_CONTENTS_URL, DATALAYER_CONTENTS_TOKEN and DATALAYER_CONTENTS_TOKEN_FILE. The token is the short-lived sandbox credential, kept out of the JSON in a file only the owner can read.

Provider	Volume mount	Shared filesystem	Bucket mount	Local bridge	Materialize	Client
`datalayer`	by the Operator	by the Operator	by the Operator	Clouder CSI	yes	yes
`daytona`	at creation	no	no	per environment: `fuse`	yes	yes
`e2b`	at creation	no	no	per environment: `fuse`	yes	yes
`modal`	at creation	no	refused: a credential would leave Contents	per environment: `fuse`	yes	yes
others	no	no	no	no	no	yes

A local bridge — a person's own folder, mounted over the bridge relay — is supported per environment, never per provider: only an environment whose metadata declares the fuse feature (fusepy and /dev/fuse in the sandbox) starts the bridge filesystem (code_sandboxes.bridge_mount) inside the sandbox, and none of the stock Daytona, E2B or Modal environments declares it. Everywhere else a local-bridge attachment is refused with LOCAL_BRIDGE_UNSUPPORTED and Synchronize is offered instead — a copy is never reported as a mount. Install the sandbox side with pip install "code-sandboxes[bridge]" in an image that exposes /dev/fuse.

See the API reference.

Manage Sandboxes (CRUD)

Every variant answers the same verbs — create, list, get, update, delete — from Python or from the CLI, rendered as rich tables:

code-sandboxes list                 # every variant that answers, one table
code-sandboxes list -v kaggle       # one variant
code-sandboxes get <id> -v modal    # one sandbox, live status
code-sandboxes create -v modal      # create detached, leave it running
code-sandboxes update <id> -v modal --tag team=ai   # tags (modal), --name
                                    # (docker), --capability (datalayer),
                                    # --code (kaggle: a new version)
code-sandboxes delete <id> -v modal --yes
code-sandboxes environments         # what sandboxes can be created in

from code_sandboxes import get_manager

manager = get_manager("modal")
for info in manager.list():
    print(info.id, info.status)
manager.delete("sb-...")

See the management guide for what each variant maps to and its connection settings.

License

BSD 3-Clause License

Release files for code-sandboxes 1.9.26

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for code-sandboxes 1.9.26
File	Size	Uploaded
code_sandboxes-1.9.26.tar.gz	1.7 MB	Sep 18, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for code-sandboxes 1.9.26
File	Interpreter	ABI	Platform	Reset
code_sandboxes-1.9.26-py3-none-any.whl 790.3 kB Sep 18, 2026	Python 3	none	any	Details

Total release size: 2.5 MB

Release files / code_sandboxes-1.9.26.tar.gz

Download URL	code_sandboxes-1.9.26.tar.gz
Size	1.7 MB
Tags	Source
SHA-256 checksum How to use checksums	`3341b74e20b0416781b570af77c75514667fb74793e9765a7bcd3ddc424a1f64`
BLAKE2b-256 checksum How to use checksums	`0150d59c7cc85947fc70e31a1200db8c52dd7d07f0cbc3298dc86209e277b391`
Upload date	Sep 18, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.11`

Release files / code_sandboxes-1.9.26-py3-none-any.whl

Download URL	code_sandboxes-1.9.26-py3-none-any.whl
Size	790.3 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`b411f3de20bb008cb2c9fe70a1e9afb828a24d88a6e1fad87805cf316af3e6cf`
BLAKE2b-256 checksum How to use checksums	`94200a1286211488e0e0505bd9a396a254767833d8bee1e34b787115ff095f10`
Upload date	Sep 18, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.11`