Beam Client

This repository contains Beam client SDKs.

Layout

• python/ contains the existing Python package and CLI release inputs.
• go/ contains the Go SDK module at github.com/beam-cloud/beam-client/go.
• js/ contains the TypeScript/JavaScript SDK package @beamcloud/beam-js.

Development

Run Go tests:

make test-go

Run live Go sandbox integration tests against the local beta9 gateway:

make test-go-integration

The integration target reads ~/.beta9/config.ini by default and requires a local gateway (localhost, 127.0.0.1, or 0.0.0.0, which the harness maps to loopback). It will fail before creating any sandbox if the resolved gateway is gateway.beam.cloud or staging. Use BEAM_TOKEN, BEAM_GATEWAY_HOST, and BEAM_GATEWAY_PORT or the matching BETA9_* variables to point at a specific local setup. For a local token that is not the default context, run:

BEAM_TOKEN=... make test-go-integration

Run runtime-specific integration targets:

make test-go-integration-runc
make test-go-integration-gvisor

The runc target uses the scheduler default pool. The gVisor target defaults BEAM_TEST_POOL to gvisor; set BEAM_TEST_POOL=... to override the pool name used by sandbox creation.

Run the optional Docker sandbox smoke on the gVisor pool:

make test-go-integration-docker

Run Python tests:

cd python && poetry run pytest

Run JS tests:

make test-js

Build the JS package:

make build-js

Build the Python CLI wheel:

cd python && poetry build -f wheel

Publish the Python package to PyPI:

POETRY_PYPI_TOKEN_PYPI=... make publish-python

Publish the JS package to npm after npm login:

make publish-js

Go SDK

The Go module is github.com/beam-cloud/beam-client/go.

Install:

go get github.com/beam-cloud/beam-client/go@latest

Pin a release:

go get github.com/beam-cloud/beam-client/go@v0.1.0

Import:

import beam "github.com/beam-cloud/beam-client/go"

Configuration

For production, set BEAM_TOKEN and call beam.NewClient(ctx). The SDK defaults to Beam's production gateway at gateway.beam.cloud:443.

export BEAM_TOKEN=...

beam.NewClient(ctx) resolves configuration in this order:

1. Explicit options such as beam.WithToken and beam.WithGateway.
2. BEAM_TOKEN, BEAM_GATEWAY_HOST, BEAM_GATEWAY_PORT.
3. BETA9_TOKEN, BETA9_GATEWAY_HOST, BETA9_GATEWAY_PORT.
4. ~/.beam/config.ini or ~/.beta9/config.ini.
5. gateway.beam.cloud:443.

For development against a local beta9 gateway, override the gateway:

export BEAM_TOKEN=...
export BEAM_GATEWAY_HOST=127.0.0.1
export BEAM_GATEWAY_PORT=1993

Sandboxes

Set SandboxConfig.Name to the app name that groups related sandboxes. Each created sandbox still has a generated container ID, available from sandbox.SandboxID().

ctx := context.Background()
client, err := beam.NewClient(ctx)
if err != nil {
    return err
}
defer client.Close()

sandbox, err := client.CreateSandbox(ctx, beam.SandboxConfig{
    Name:  "example",
    Image: beam.NewImage(beam.WithPythonVersion("python3.11")),
})
if err != nil {
    return err
}
defer sandbox.Terminate(context.Background())

result, err := sandbox.RunCode(ctx, "print('hello from Beam')", beam.ExecOptions{})
if err != nil {
    return err
}
fmt.Print(result.Stdout)

Use sandbox.Status, sandbox.Poll, and sandbox.Wait when you need to observe sandbox lifecycle state. CreateSandbox waits for the sandbox to be ready before returning.

Processes And Logs

Use Exec for argv-safe command execution and ExecShell when you intentionally want shell text sent as-is. Process stdout and stderr reads are consumptive server deltas, so use Process.Output for a completed result or Process.Stream for live logs.

proc, err := sandbox.Exec(ctx, []string{"sh", "-lc", "echo out; echo err >&2"}, beam.ExecOptions{})
if err != nil {
    return err
}
exitCode, err := proc.Stream(ctx, func(entry beam.LogEntry) {
    fmt.Print(entry.Data)
})

Files, Volumes, Docker, And Snapshots

Sandbox filesystem APIs are available through sandbox.FS. Beam volumes and cloud buckets are configured with beam.NewVolume and beam.NewCloudBucket. Secrets and GPUs are configured directly on SandboxConfig.

sandbox, err := client.CreateSandbox(ctx, beam.SandboxConfig{
    Name:     "resources-example",
    Image:    beam.NewImage(beam.WithPythonVersion("python3.11")),
    GPU:      "T4",
    GPUCount: 1,
    Secrets:  []string{"MY_SECRET"},
    Volumes: []beam.VolumeMount{
        beam.NewVolume("cache", "/mnt/cache"),
        beam.NewCloudBucket("/mnt/bucket", beam.CloudBucketConfig{
            BucketName: "my-bucket",
            Region:     "us-east-1",
            ReadOnly:   true,
        }),
    },
})

Docker-in-Docker requires both Image.WithDocker() and SandboxConfig.DockerEnabled. Docker helpers default inner containers and Compose services to host networking/PID mode so they work under both runc and gVisor sandbox runtimes.

sandbox, err := client.CreateSandbox(ctx, beam.SandboxConfig{
    Name:          "docker-example",
    Image:         beam.NewImage(beam.WithPythonVersion("python3.11")).WithDocker(),
    DockerEnabled: true,
})
if err != nil {
    return err
}
proc, err := sandbox.Docker.Run(ctx, "busybox:1.36", beam.DockerRunOptions{
    Remove:  true,
    Command: []string{"sh", "-c", "echo hello"},
})

Use SnapshotMemory to checkpoint a sandbox and CreateSandboxFromMemorySnapshot to restore it:

checkpointID, err := sandbox.SnapshotMemory(ctx)
restored, err := client.CreateSandboxFromMemorySnapshot(ctx, checkpointID)

Runnable sandbox examples live in go/examples:

cd go
export BEAM_TOKEN=...
go run ./examples/basic
go run ./examples/filesystem
go run ./examples/http
go run ./examples/snapshot
go run ./examples/docker
go run ./examples/resources

Releases

Python CLI: create a GitHub release named cli-X.Y.Z. release-cli.yml builds the wheel from python/ and embeds it in the platform CLI binaries with PyApp.

Go SDK: tag the go/ submodule as go/vX.Y.Z:

git tag go/v0.1.0
git push origin go/v0.1.0

Go users request the module version without the subdirectory prefix:

go get github.com/beam-cloud/beam-client/go@v0.1.0

release-go.yml checks the tag shape, runs Go tests, and verifies that a fresh module can fetch and import github.com/beam-cloud/beam-client/go from GitHub. The Go SDK publishes through the Git tag; it has no binary artifact.

JavaScript SDK: create a GitHub release or tag named js/vX.Y.Z:

git tag js/v1.2.3
git push origin js/v1.2.3

release-js.yml installs dependencies in js/, sets the package version from the tag, runs tests, builds the package, and publishes @beamcloud/beam-js to npm. Prereleases publish under the rc npm tag.