Reference · JS / TS SDK

JS / TS SDK

Public surface of the grotte npm package. Hand-curated from JSDoc — see the package source for full type signatures.

Install

bash

npm install grotte

The single export everything starts from:

import Sandbox from "grotte";
// or named:
import { Sandbox, AsyncSandbox } from "grotte";

The default Sandbox export is async (every method returns a Promise). There's no separate sync entrypoint in JS — runtime is async by nature.

`Sandbox`

Lifecycle

Method	Returns	Description
`Sandbox.create(template?, opts?)`	`Promise<Sandbox>`	Create a new sandbox from a template (or default `base`).
`Sandbox.connect(sandboxId, opts?)`	`Promise<Sandbox>`	Reconnect to a running sandbox by id.
`Sandbox.list(opts?)`	`SandboxPaginator`	List sandboxes (running by default). Iterate with `for await (const sb of paginator) { ... }`.
`sandbox.isRunning(opts?)`	`Promise<boolean>`	Health probe.
`sandbox.kill(opts?)`	`Promise<void>`	Terminate immediately.
`sandbox.pause(opts?)`	`Promise<boolean>`	Pause + persist filesystem.
`sandbox.resume(opts?)`	`Promise<this>`	Resume a paused sandbox. Alias for `connect()`.

const sandbox = await Sandbox.create("base");
const result = await sandbox.commands.run('echo "Hello"');
console.log(result.stdout);
await sandbox.kill();

Timeout / TTL

Method	Returns	Description
`sandbox.setTimeout(ms, opts?)`	`Promise<void>`	Set total max lifetime (from now).
`sandbox.updateTimeout(ms, opts?)`	`Promise<void>`	Adjust the timeout in flight.
`sandbox.refreshTtl(seconds, opts?)`	`Promise<void>`	Add seconds to the current TTL (heartbeat-style).

Network

Method	Returns	Description
`sandbox.setNetwork({ internet_access }, opts?)`	`Promise<void>`	Toggle outbound internet access. Defaults to enabled.

await sandbox.setNetwork({ internet_access: false }); // cut egress

Snapshots

Method	Returns	Description
`sandbox.createSnapshot(opts?)`	`Promise<SnapshotInfo>`	Snapshot the current filesystem state into a reusable template.

URLs

Method	Returns	Description
`sandbox.getHost(port)`	`string`	Host-only string (`<port>-<id>.sandbox.grotte.parallactic.fr`).
`sandbox.getUrl(port)`	`string`	Full `https://…` URL — wraps `getHost`. Prefer this for browser links and HTTP clients.
`sandbox.uploadUrl(path?, opts?)`	`Promise<string>`	Pre-signed upload URL.
`sandbox.downloadUrl(path, opts?)`	`Promise<string>`	Pre-signed download URL.

MCP

Method	Returns	Description
`sandbox.getMcpToken()`	`Promise<string \| undefined>`	Token for MCP gateway access from inside the sandbox.

`sandbox.filesystem`

Method	Returns	Description
`read(path, opts?)`	`Promise<string \| Uint8Array \| Blob>`	Read a file. Format inferred from `opts.format` — `text` (default), `bytes`, `blob`, `stream`.
`write(path, content, opts?)`	`Promise<void>`	Write a file. `content` accepts `string`, `Uint8Array`, or a stream.
`writeFiles(files, opts?)`	`Promise<void>`	Batch-write many files in one round-trip.
`list(path, opts?)`	`Promise<EntryInfo[]>`	List directory entries.
`makeDir(path, opts?)`	`Promise<boolean>`	mkdir -p.
`rename(src, dst, opts?)`	`Promise<void>`	Rename / move.
`remove(path, opts?)`	`Promise<void>`	rm -rf.
`exists(path, opts?)`	`Promise<boolean>`	Check if a path exists.

await sandbox.filesystem.write("/tmp/hello.txt", "world");
const contents = await sandbox.filesystem.read("/tmp/hello.txt");
console.log(contents); // "world"

`sandbox.commands`

Method	Returns	Description
`run(command, opts?)`	`Promise<CommandResult>`	Run a command, wait for exit, return `{ stdout, stderr, exitCode }`.
`connect(pid, opts?)`	`Promise<CommandHandle>`	Attach to an already-running command (returns a handle with stdout/stderr streams).
`list(opts?)`	`Promise<ProcessInfo[]>`	List currently-running processes.
`kill(pid, opts?)`	`Promise<boolean>`	SIGKILL a process by pid.
`sendStdin(pid, data, opts?)`	`Promise<void>`	Pipe data into a running process's stdin.
`closeStdin(pid, opts?)`	`Promise<void>`	EOF a running process's stdin.

const result = await sandbox.commands.run("python -c 'print(2+2)'");
console.log(result.stdout); // "4\n"

For long-running commands, drop --background-style by passing background: true and reading from the returned handle's streams:

const handle = await sandbox.commands.run("npm run dev", {
  background: true,
});
for await (const chunk of handle.stdout) process.stdout.write(chunk);

Templates (build-time)

The Template builder is for authoring custom templates programmatically — see Defining a template for the full guide.

import { Template } from "grotte";
 
export const template = Template()
  .fromImage("ubuntu:22.04")
  .runCmd("apt-get update && apt-get install -y python3-pip")
  .runCmd("pip install pandas")
  .setWorkdir("/opt/work");

Common option types

Every method accepts an opts object with at least:

Key	Type	Description
`requestTimeoutMs`	`number`	Per-request timeout.
`signal`	`AbortSignal`	Cancellation.

Auth is read from process.env.GROTTE_API_KEY by default; override per-call via opts.apiKey.