SDK Reference
Programmatic reference for Sandbox covering installation, authentication, client options, identity discovery, OpenCode integration, and error types.
Sandbox has official SDKs for Go, TypeScript, and Python. All three wrap the same public service contract (tenki.sandbox.v1), so you get equivalent functionality whichever language you choose.
Install
npm install @luxorai/sandboxLegacy names
The SDKs were published under Tenki names, and those still work: the @tenkicloud/sandbox npm package (with TenkiSandbox as an alias of LuxorSandbox), the tenki PyPI package (import tenki), Go versions before 1.5.0 at github.com/LuxorLabs/tenki-sdk-go/sandbox, the TENKI_* environment variables, and API keys that start with tk_.
Authenticate
The public SDKs authenticate with Workspace API keys (lx_...), sent as Authorization: Bearer <token>. Each key
is bound to one workspace, and Sandbox requests infer that workspace automatically.
Resolution order
Every SDK resolves the auth token the same way: the token you pass explicitly (WithAuthToken() in Go, authToken in TypeScript, auth_token= in Python), then LUXORAI_AUTH_TOKEN, then LUXORAI_API_KEY, then the TENKI_AUTH_TOKEN and TENKI_API_KEY fallbacks.
The base URL resolves the same way: the explicit option (WithBaseURL() / baseUrl / base_url=), then LUXORAI_API_ENDPOINT, then LUXORAI_API_URL, then the TENKI_API_ENDPOINT and TENKI_API_URL fallbacks, then the default: https://api.luxor.ai in current releases, https://api.tenki.cloud in earlier ones. Both hosts serve the same API.
Create a client
import { LuxorSandbox } from "@luxorai/sandbox";
const sandbox = new LuxorSandbox(); // env-driven
// Or explicit:
const sandbox = new LuxorSandbox({
authToken: "lx_...",
baseUrl: "https://api.luxor.ai",
});To create and drive a session, every SDK and the CLI accept the same set of options. See Create a session for the full list. For moving files in and out of a sandbox — read, write, list, stat, delete, and chunked streaming — see File operations; there is no need to shuttle base64 through exec.
Defaults
Defaults applied by Create when you do not override them:
cpu:2memory:4096 MB
Inbound and outbound networking are both enabled by default in every SDK and the CLI, subject to workspace restrictions and any session allowlist.
Pass allowInbound: false (--allow-inbound=false) at create time to disable inbound exposure, or allowOutbound: false (--allow-outbound=false) to disable outbound access.
Network settings cannot be changed on an existing session.
Every SDK reports what a session was created with; see Port exposure and networking.
Validation: cpu_cores 1..16, memory_mb 512..65536, volume size 1 MiB to 50 GiB.
Outbound allowlist options
Available in every release of @luxorai/sandbox, luxor-ai and go.luxor.ai/sandbox, and in 1.1.0 or later of the legacy packages.
These create-time options require session egress policies to be enabled for your workspace first (ask support).
For a single destination IP, use a /32 prefix, for example allowCidrs: ["203.0.113.10/32"] in TypeScript.
Replace this documentation address with your destination's IPv4 address.
You can pass either list or both.
Omitting both lists, or passing empty lists, adds no session restriction.
Disabling outbound access still blocks outbound traffic even if an allowlist is supplied.
Each SDK returns a SessionEgressPolicy containing the normalized session allowlist:
Python returns tuples for both fields and supports the same options and policy accessors in its async SDK.
The returned policy does not include workspace restrictions; empty lists do not guarantee unrestricted outbound access.
The domain lists accept *.example.com for one subdomain label and **.example.com for any depth.
See Outbound allowlists for examples, wildcard matching, limits, and workspace enablement errors.
Identity
Use WhoAmI to inspect the authenticated owner and its workspace. Normal resource calls do not need the
workspace ID; the API key already supplies that scope.
const me = await sandbox.whoAmI();
console.log(`${me.ownerType}/${me.ownerId}`);OpenCode integration
Sessions can run OpenCode inside the VM for AI-driven workflows. Enable it at create time with the enableOpenCode option (WithOpenCode in Go, enable_opencode in Python). In the TypeScript and Go SDKs you can also pass a provider option (openCodeProvider / WithOpenCodeProvider) to wire in your keys. See Create a session for those options.
OpenCode then runs inside the session. The SDKs enable it at create time but do not expose an API for driving it programmatically once the session is running.
Git helpers
The SDK exposes structured Git operations on a session.
await session.git.clone("https://github.com/org/repo", { depth: 1 });
await session.git.checkout("feature");
const diff = await session.git.diff({});
const log = await session.git.log({ maxCount: 10 });
await session.git.fetchPR(42, { remote: "origin" });Every helper returns the raw git output as a string. log takes a commit cap, a revision range, and a path filter (maxCount/max_count/MaxCount, range/Range, path/Path). diff takes the same revision range and path filter, plus base/Base and head/Head to name the two ends separately instead of as a range.
Each helper also takes a directory (Directory in Go), the repository to run in. It is the equivalent of git -C. Pass it whenever the repo was cloned into a subdirectory rather than the default working directory, or the operation runs against the wrong tree.
You can also inject a GitHub token at session create time (WithGitHubToken(token) in Go, the githubToken option in TypeScript, or github_token= in Python) so private clones work without provisioning credentials inside the guest.
Registry version pruning
Published registry versions pin their source snapshots. Delete an eligible historical version to release that pin; the version must be untagged, not the image's latest version, and unused by a share. The SDK methods take the registry image ID and snapshot ID, and return both IDs after deletion.
const deleted = await sandbox.deleteRegistryImageVersion(imageId, snapshotId);
console.log(deleted.imageId, deleted.snapshotId);Deleting a latest, tagged, or shared version fails with a failed-precondition error, and the message names the rule that blocked it. Deleting the registry version does not delete the snapshot; call the snapshot deletion API separately after the pin is released.
Constants
The default operation timeouts are the same across SDKs:
Each SDK exports them as named constants: Go DefaultSessionCreateTimeout and friends, TypeScript DEFAULT_SESSION_CREATE_TIMEOUT_MS (milliseconds), and Python DEFAULT_CREATE_TIMEOUT (seconds, in tenki_sandbox.constants).
For volume sizes, the SDKs export byte-multiplier constants (KB, MB, GB, and the binary KiB, MiB, GiB, and so on):
import { GiB } from "@luxorai/sandbox";
const tenGiB = 10 * GiB;Errors
Every SDK surfaces service errors as typed values, sharing a common base (SandboxError in the TypeScript and Python SDKs). The common ones:
The Go SDK also defines ErrSSHUnavailable and ErrVolumeLimitExceeded.
FileTooLargeError means a non-streaming read or write passed 32 MiB (SDK 1.4.3 or later).
It carries the operation, the file size, and the limit; use the streaming calls instead.
See File operations.
WaitReadyFailedError and TemplateRuntimeFailedError carry a live sandbox handle when the service admitted the sandbox before readiness failed.
The sandbox exists and bills until you close it.
See Create and wait.
Catch errors the idiomatic way in each tool:
import { CommandTimeoutError } from "@luxorai/sandbox";
try {
await session.exec("sleep", { args: ["999"], timeoutMs: 1000 });
} catch (err) {
if (err instanceof CommandTimeoutError) {
console.log("Command timed out");
}
}Advanced API surface
The public service contract also exposes lower-level RPCs that the convenience SDKs don't wrap:
PauseSession,ResumeSession: present in the protobuf, not always wrapped, may not be available in every deployment
If you need them, integrate directly with the protocol:
proto/tenki/sandbox/v1/sandbox.proto
Stick to the SDKs unless you need a raw RPC
The Go, TypeScript, and Python SDKs are the officially supported surface for Sandbox. Only drop down to raw Connect/gRPC when an RPC isn't yet wrapped by an SDK, and keep in mind that a wrapper may be added in a future release.