Docker in Sandboxes - Beam

Install Docker in the image and enable it on the sandbox:

from beam import Image, Sandbox

sb = Sandbox(
    image=Image(python_version="python3.11").with_docker(),
    docker_enabled=True,
    cpu=2,
    memory="4Gi",
    keep_warm_seconds=600,
).create()

try:
    result = sb.docker.run("hello-world", remove=True)
    result.wait()
    print(result.stdout)
finally:
    sb.terminate()

Set docker_enabled=True and include Docker in the image. with_docker() installs it for you.

Build and Run

sb.fs.create_directory("/workspace/app")
sb.fs.write_text("/workspace/app/Dockerfile", "FROM alpine:3.20\nCMD [\"echo\", \"hello\"]\n")
build = sb.docker.build(tag="example:latest", context="/workspace/app")
build.wait()
print(build.success)

run = sb.docker.run("example:latest", remove=True)
run.wait()
print(run.stdout)

Commands return a DockerResult with wait(), stdout, stderr, and success. You can also pull, push, tag, list, and remove images or containers.

Networking and Compose

Docker containers share the sandbox’s network. Expose a service with sb.expose_port(PORT); host-port remapping is not supported. Upload your Compose file and source into the sandbox before starting the stack:

sb.fs.upload_file("compose.yaml", "/workspace/compose.yaml")
stack = sb.docker.compose_up(file="compose.yaml", cwd="/workspace")
print(stack.ps().output)
stack.stop()

compose_up returns a handle with logs, ps, and stop. Use sb.aio.docker for async calls.