SDK Reference

Tenki 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 @tenkicloud/sandbox

Authenticate

The public SDKs authenticate with Workspace API keys (tk_...), 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 TENKI_AUTH_TOKEN, then TENKI_API_KEY.

The base URL resolves the same way: the explicit option (WithBaseURL() / baseUrl / base_url=), then TENKI_API_ENDPOINT, then the legacy TENKI_API_URL, then https://api.tenki.cloud.

Create a client

import { TenkiSandbox } from "@tenkicloud/sandbox";

const sandbox = new TenkiSandbox(); // env-driven

// Or explicit:
const sandbox = new TenkiSandbox({
  authToken: "tk_...",
  baseUrl: "https://api.tenki.cloud",
});

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: 2
• memory: 4096 MB

Inbound and outbound networking are both enabled by default, in every SDK and the CLI. A fresh session can reach the internet, so npm install, pip install, and git clone work without extra options. Pass allowInbound: false (--allow-inbound=false) at create time to opt out of inbound exposure; 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.

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 "@tenkicloud/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.

WaitReadyFailedError and TemplateRuntimeFailedError are the two that carry a live sandbox handle: the service admitted the sandbox before readiness failed, so it exists and bills until you close it. See When a create never turns ready.

Catch errors the idiomatic way in each tool:

import { CommandTimeoutError } from "@tenkicloud/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