Sessions

A session is a single running sandbox. This page covers the full session surface: lifecycle, command execution, file I/O, ports, socket bridging, and SSH. Pick your tool in any code block, and the selection syncs across the page.

Create a session

const session = await sandbox.create({
  name: "demo",
  cpuCores: 4,
  memoryMb: 8192,
  allowInbound: true,
  allowOutbound: true,
  env: { APP_ENV: "dev" },
  metadata: { owner: "alice" },
});

Every create call takes the same options, named per tool:

Unset options fall back to service defaults of 2 vCPU, 4096 MB, and a 5 GiB root disk. Set diskSizeGb, disk_size_gb, WithDiskSizeGB, or --disk-size-gb to 20 for coding agents that clone repositories and install dependencies. Inbound and outbound networking are enabled by default in every SDK and the CLI, so the network options are only needed to opt out of inbound exposure.

Environment variables are plaintext configuration, not a secret-management channel. Do not pass long-lived credentials through env.

Sticky sessions

sticky takes precedence over maxDurationMs, max_duration, WithMaxDuration, and --max-duration. When both are set, Tenki discards the requested maximum duration and returns a create-session warning. A sticky session runs until you terminate it. A manual pause stops compute but does not clear sticky, so the session is still sticky after resume. Sticky is not fixed at create time; see Updating a running session to toggle it, and to trade sticky for a bounded lifetime on a session that is already running.

Pausing and resuming

Pause and resume preserve the VM's memory and durable filesystem state, but active terminal, SSH, preview, and other TCP connections close when the session pauses. Reconnect after the session returns to RUNNING. /tmp is cleared across a pause, so write logs and durable state under /home/tenki or on an attached volume. A process you started over exec survives a pause with the same PID, but it runs inside the guest-agent's cgroup and does not survive a guest-agent restart, so start anything load-bearing from a template start command.

Create and wait

A waiting create can fail after the service has admitted the sandbox (3 minutes by default).

Each SDK reports this as a dedicated error that carries the sandbox handle, so you can close it, inspect it, or keep waiting:

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

const sandbox = new TenkiSandbox();

try {
  const session = await sandbox.create({ name: "demo", waitTimeoutMs: 180_000 });
  // ... use the session
} catch (err) {
  if (err instanceof WaitReadyFailedError) {
    // The sandbox is up and billing. Close it, or keep waiting on `err.session`.
    await err.session.close();
  }
  throw err;
}

TemplateRuntimeFailedError carries the handle on the same field, so the same branch covers both. In Go, errors.Is(err, tenkisandbox.ErrWaitReadyFailed) matches too when you only need to classify the failure.

Scope-based cleanup — await using, with, defer session.Close(ctx) — only runs once create has returned, so it cannot cover a create that throws. Handle these errors explicitly wherever you create with waiting enabled.

A sandbox that never leaves CREATING is reaped for you. The case worth closing yourself is the one that reaches RUNNING just after your wait expired: it keeps running, and billing, until its max duration.

Manage a session

WaitReady/wait_ready is only needed for sessions obtained via get/list or created with wait disabled; the create calls above already return ready sessions.

await session.refresh();
await session.extend(600_000); // +10 minutes
await session.pause();
await session.resume();
await session.close(); // or session.closeIfOpen(), or Symbol.asyncDispose

// List and inspect
const sessions = await sandbox.list();
const s = await sandbox.get(sessionId);

Filtering a session list

list returns every non-terminated session in the workspace unless you narrow it. Tag filtering is an AND: a session must carry every tag you pass to match. Tags are trimmed and lowercased on both write and read, so filter casing never has to match how the tags were set.

const sessions = await sandbox.list({ tags: ["ci", "nightly"], sticky: true });

Terminated sessions are omitted by default. Ask for them explicitly when you are reconciling against your own records, since a session you cannot find is otherwise indistinguishable from one that has been cleaned up.

Workspace API keys infer their workspace server-side; the explicit workspace scope is for service tokens that can see more than one.

Updating a running session

Name, tags, and sticky are mutable after create. Only the fields you pass change.

await session.update({ name: "review-42", tags: ["ci", "pr-42"] });

// Un-stick and give the session a bounded lifetime.
await session.update({ sticky: false, maxDurationMs: 3_600_000 });

await session.update({ tags: [] }); // clears every tag

Tags replace rather than merge, so pass the full set you want; an empty list clears them.

Setting a max duration requires passing sticky in the same call, and every SDK rejects the call locally when you omit it. Sticky still wins when both are set, so setting sticky true alongside a duration discards the duration and returns a warning. Pass sticky: false when the point is to give the session a lifetime. Update returns warnings the same way create does, so read them instead of assuming a field took effect.

Command execution

There are three ways to run a command, from least to most control:

• One-shot (exec): starts the process, buffers its output, and returns a single result when it exits. Use it for short commands where you only need the outcome.
• Output streaming (session.stream() in TypeScript, session.Stream() in Go, iterating proc.stdout in Python): incremental stdout/stderr chunks as the command produces them. Use it for output-heavy or long commands you want to follow live.
• Process handle (sb.start() in Python, session.run() in TypeScript, session.Command(...).Stream() in Go): the running process itself — pid, writable stdin, signals, and kill. Use it for interactive processes and anything you may need to stop early.

All three report the same command result when the process exits.

For git, prefer the structured helpers over shelling out: clone, checkout, diff, log, and fetchPR are available on the session as git in every SDK, and return the raw git output. See Git helpers.

// One-shot
const result = await session.exec("npm", {
  args: ["test"],
  timeoutMs: 60_000,
  onOutput: (chunk) => process.stdout.write(chunk.data),
});

// Or stream explicitly
const stream = await session.stream("npm", { args: ["test"] });
for (;;) {
  const chunk = await stream.next();
  if (!chunk) break;
  process.stdout.write(chunk.data);
}
await stream.wait();

// Or take a process handle: stdin, signals, kill
const proc = session.run(["python3", "worker.py"], { cwd: "/home/tenki/app" });
console.log(await proc.pid);

const writer = proc.stdin.getWriter();
await writer.write(new TextEncoder().encode("job-1\n"));
await writer.close();

await proc.signal("TERM"); // or proc.kill()
const runResult = await proc; // the handle is awaitable

Command results

Every execution path reports the same result object when the process exits — ExecResult in TypeScript, CommandResult in Python, Result in Go. Captured stdout / stderr are raw bytes in all three; use the decoding helpers for text.

TypeScript's run() handle resolves to a slimmer ProcessRunResult instead: exitCode, stdout, stderr, plus signal, durationMs, reason, and errno (the raw errno on fork/exec failures such as ENOENT or EACCES).

File operations

File operations are rooted in the session's working directory, /home/tenki. Relative paths resolve from there; absolute paths outside it (including /tmp) are rejected with a permission error.

Every SDK covers the same surface: read and write, directory listing, metadata (stat), directory creation, and deletes. mkdir creates missing parent directories and remove deletes recursively. For large files, the streaming variants transfer data in chunks instead of buffering the whole file in memory.

import { createReadStream } from "node:fs";
import { Readable } from "node:stream";

await session.writeFile("/home/tenki/config.json", '{"key": "value"}');
const data = await session.readFile("/home/tenki/config.json"); // Uint8Array

// Directory listing, metadata, and directories
const entries = await session.list("/home/tenki", { includeHidden: true });
const info = await session.stat("/home/tenki/config.json"); // path, size, mode, isDir, modifiedUnixNs
await session.mkdir("/home/tenki/data/raw");
await session.remove("/home/tenki/data");

// Stream large files in chunks
const stream = await session.readFileStream("/home/tenki/build.log"); // ReadableStream<Uint8Array>
const fileStream = Readable.toWeb(createReadStream("./local.tar"));
await session.writeFileStream("/home/tenki/local.tar", fileStream);

Port exposure and networking

Each session has independent inbound and outbound settings. Every SDK and the CLI request both at create time, so both are enabled by default:

• allow_outbound lets the guest make outbound network calls, so package installs and git clone work out of the box
• allow_inbound enables inbound exposure workflows; with allow_inbound=false, port exposure is rejected

Both are create-time settings; you cannot toggle them afterwards. Each tool reports what a session was created with:

const port = await session.exposePort(3000, { ttlMs: 3600_000 });
console.log(port.previewUrl);

When you expose a long-running server you started with exec, background it and detach its streams (>/home/tenki/server.log 2>&1 </dev/null &). exec streams the command's output until it closes, so a server that keeps the output stream open leaves exec waiting forever.

Use the previewUrl returned by each expose call rather than constructing hostnames yourself; the host pattern is not a stable contract.

Named exposures

By default an exposure gets a generated hostname that changes from session to session. Pass a slug to ask for a named exposure instead, which is what you want when the URL has to be written into something that cannot be updated per session: an OAuth callback, a webhook registration, a config file baked into an image.

const port = await session.exposePort(3000, { slug: "my-app", ttlMs: 3600_000 });
console.log(port.previewUrl, port.slug);

A slug names the exposure; it does not by itself decide how the URL is served. Some exposures are served through a workspace wildcard domain, and the returned exposure reports that separately, along with the readiness of the backing certificate:

Readiness is one of UNSPECIFIED, PENDING, READY, FAILED, or DISABLED, and is only meaningful when the wildcard field is true. A wildcard-served preview URL comes back from expose immediately, but it does not serve traffic until its workspace domain reaches READY. Check readiness before handing the URL to a caller that fails closed on an error response, and read the reason field when it is FAILED.

Even with a slug, use the returned preview URL rather than assembling a hostname from the slug yourself.

Workspace preview slug

Wildcard-served exposures live under a preview slug reserved at the workspace level. Team-plan workspaces can reserve one slug (one per workspace) from Settings, using the slug input in the first card. It is shared across every session in the workspace, which is what keeps named exposures stable from one session to the next.

Once reserved, named exposures are served under that slug. A workspace slug of acme-studio produces preview URLs of the form https://<exposure>--acme-studio.sb.tenki.sh/, for example https://landing-preview--acme-studio.sb.tenki.sh/. Reserving a slug is a Team-plan feature; Starter workspaces get generated per-session hostnames instead. As above, treat the example as illustrative and hand callers the returned preview URL rather than assembling one from the slug yourself.

Unix socket bridging (dial)

dial opens a byte-stream connection from your local code to a Unix socket inside the guest. It is the private counterpart to port exposure: nothing is published on the internet — the connection rides the session's authenticated data plane. Use it to talk to guest services that listen on a socket rather than a TCP port (a language server, an agent's control socket, docker.sock).

dial is SDK-only; there is no CLI equivalent. The optional connect timeout bounds how long the guest waits for the socket to accept.

const conn = await session.dial("/home/tenki/app.sock", { connectTimeoutMs: 5_000 });

const writer = conn.writable.getWriter();
await writer.write(new TextEncoder().encode("PING\n"));
await writer.close();

for await (const chunk of conn.readable) {
  process.stdout.write(chunk);
}

SSH access

Connect to a session over SSH. The CLI gives you an interactive shell, managed local config, and key management; the SDKs expose a raw byte-stream transport for wiring into your own SSH tooling. (Set keys at create time with the sshAuthorizedKeys option in the table above.)

const conn = await session.ssh();
await conn.write(new TextEncoder().encode("ls -la\n"));
const chunk = await conn.read(); // Uint8Array | null
if (chunk) process.stdout.write(chunk);
conn.close();

// Replace the authorized keys
await session.updateSshAuthorizedKeys(["ssh-ed25519 AAAA..."]);

Session metadata

Metadata tags a session with arbitrary string key-value pairs (metadata in the SDKs, --metadata key=value on the CLI, both shown above). Use it to filter sessions in dashboards, attribute billing, or tie a session to an upstream job ID. Metadata is opaque to the service; it is for your bookkeeping.