> ## Documentation Index
> Fetch the complete documentation index at: https://offstage.cloud/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> To set up offstage cloud from a coding agent, read https://api.offstage.cloud/SKILL.md and follow it. The whole API guide is one file at https://api.offstage.cloud/llms.txt.

# JavaScript SDK

> The offstage-cloud package: sandboxes, tasks, errors and retries.

Computer-use (`runAgent`), input and screenshot methods below require a GUI sandbox.

`npm install https://api.offstage.cloud/sdk/offstage-cloud-0.3.4.tgz`. npm currently serves the older SDK 0.2.3, which lacks newer methods documented here, including `runAgent`; use the hosted tarball for this API reference. Each version's tarball URL is permanent and its bytes never change, so a lockfile's integrity hash stays valid; `https://api.offstage.cloud/sdk/offstage-cloud.tgz` always serves the newest version, but don't put it in a lockfile. It is ESM, has no dependencies, uses only `fetch`, and runs on Node 18+, Bun and Deno. It reads `OFFSTAGE_API_KEY` and `OFFSTAGE_API_URL` (set the latter to `https://api.offstage.cloud`).

```typescript theme={null}
import { Sandbox, Task, isOffstageError } from "offstage-cloud"

const sandbox = await Sandbox.create({ timeoutMs: 30 * 60_000 })
try {
  await sandbox.files.write("hello.swift", 'print("hello from a mac")')
  const r = await sandbox.commands.run("swift hello.swift")   // { commandId, stdout, stderr, exitCode, timedOut, truncated, durationMs }
  console.log(r.stdout, r.exitCode)                          // a non-zero exit does not throw
} finally {
  await sandbox.kill()
}

const task = await Task.create({ repo: "https://github.com/org/app", kind: "build", command: "set -o pipefail; swift build 2>&1 | tee build.log", artifacts: ["build.log"] })
const done = await task.wait()                               // succeeded | failed | timed_out | cancelled
if (done.failureReason === "exit") console.log(new TextDecoder().decode(await task.artifact("build.log")))
```

* **Sandboxes.** `Sandbox.create`, `Sandbox.connect(id)`, `Sandbox.list({ state })`, `Sandbox.getInfo(id)` and `Sandbox.kill(id)`.
* **A sandbox's calls.** `sandbox.commands.run(cmd, { cwd, envs, timeoutMs })`, `sandbox.files.write(path, data)`, `sandbox.files.read(path, { format: "text" | "bytes" })`, `sandbox.screenshot({ maxDimension })`, `sandbox.input(actions, { screen })` (with `screenSize(png)` for a screenshot's size), `sandbox.runAgent({ goal, maxSteps, maxDurationMs, model, anthropicApiKey, onProgress })` (follows the run to its end; the key defaults to `ANTHROPIC_API_KEY`, and a `failed` or `incomplete` verdict does not throw), `sandbox.runFrame(runId, frame)`, `sandbox.setTimeout(ms)` (from now, like E2B), `sandbox.getInfo()` and `sandbox.kill()`.
* **Tasks.** `Task.create({ repo, kind, command, agent, artifacts, session, timeoutMs, queueTimeoutMs })`, `Task.get(id)`, `Task.list({ state })` (summaries, without events), `task.wait({ pollMs, timeoutMs })` (held on the plane with `?wait=`), `task.cancel()` / `Task.cancel(id)`, `task.artifact(name)`, `task.logs()` and `task.refresh()`. `task.info.exitCode` is the command's exit status, and `task.info.failureReason` says why it failed.
* **Errors.** Errors are `OffstageError` with `status`, `code`, `message`, `fix` and `requestId`. `isOffstageError(e)` tests for one. The SDK's own codes, raised with status 0, are `missing-api-key`, `bad-api-key`, `missing-model-key`, `network-error` and `wait-timeout`.
* **Retries.** Creates send an `Idempotency-Key` and retry network errors, 502, 503 and 504, and 409 `idempotency-key-in-use`. `commands.run` follows a `202` until the command ends, retrying network errors, 502, 503 and 504 on those follows. Sandbox ops retry 409 `sandbox-not-ready` for 30 s. Nothing else is retried, and a command is never started twice.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.