Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 47 additions & 0 deletions .github/workflows/typescript.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
name: TypeScript SDK

on:
push:
branches: [main]
paths:
- ".github/workflows/typescript.yml"
- "packages/typescript/**"
pull_request:
paths:
- ".github/workflows/typescript.yml"
- "packages/typescript/**"

concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true

permissions:
contents: read

jobs:
check:
runs-on: blacksmith-2vcpu-ubuntu-2404
defaults:
run:
working-directory: packages/typescript
steps:
- uses: actions/checkout@v6
with:
persist-credentials: false

# packages/typescript is empty until the first Copybara import from useblacksmith/web.
- id: package
run: test -f package.json && echo "present=true" >> "$GITHUB_OUTPUT" || echo "present=false" >> "$GITHUB_OUTPUT"

- uses: actions/setup-node@v6
if: steps.package.outputs.present == 'true'
with:
node-version: "24"

- if: steps.package.outputs.present == 'true'
run: |
npm install --no-audit --no-fund
npm run build
npm run check:types
npm run check:lint
npm test
4 changes: 4 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
dist/
node_modules/
package-lock.json
pnpm-lock.yaml
21 changes: 21 additions & 0 deletions LICENSE
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
MIT License

Copyright (c) 2026 Blacksmith Software, Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
84 changes: 78 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,85 @@
# Blacksmith Sandbox SDKs

Client libraries for [Blacksmith](https://blacksmith.sh) sandboxes, one directory per language:
Client libraries for [Blacksmith](https://blacksmith.sh) sandboxes: fast-booting
microVMs with an HTTP API for running commands, managing long-lived processes,
streaming their output, moving files, exposing ports and pausing/resuming.
This repository hosts one SDK per language under `packages/`.

| Language | Package | Path |
| ---------- | ------------------------ | --------------------- |
| TypeScript | `@useblacksmith/sandbox` | `packages/typescript` |
| Language | Package | Path | Status |
| ---------- | ------------------------------------------------------------------------ | --------------------- | ------- |
| TypeScript | [`@useblacksmith/sandbox`](https://www.npmjs.com/package/@useblacksmith/sandbox) | `packages/typescript` | Preview |
| Python | | `packages/python` | Planned |

Each package has its own README with installation and a quickstart.
Each package ships its own README with installation, a quickstart and the full
API reference.

## Quickstart (TypeScript)

```sh
npm install @useblacksmith/sandbox
```

```ts
import { HttpControlPlaneClient, Sandbox } from "@useblacksmith/sandbox";

const cp = new HttpControlPlaneClient({ apiKey: process.env.BLACKSMITH_API_KEY! });
const sandbox = await Sandbox.create(cp, { image: "ubuntu-24.04" });

const { exit_code, stdout } = await sandbox.exec({ cmd: ["uname", "-a"] });
console.log(exit_code, stdout);

await sandbox.writeFile("/work/build.sh", "#!/bin/sh\necho building\n", { mode: 0o755, mkdirParents: true });
await sandbox.startProcess("build", { cmd: ["/work/build.sh"], cwd: "/work" });
for await (const chunk of sandbox.streamOutput("build", { follow: true })) {
if (chunk.type === "stdout") process.stdout.write(chunk.data);
}

await sandbox.delete();
```

## How the SDKs are built

Every sandbox exposes two HTTP surfaces, and each SDK keeps them apart:

- **Control plane** — the Blacksmith API (`https://api.blacksmith.sh`). Creates,
lists, pauses, resumes and deletes sandboxes and mints short-lived tokens for
the agent. Authenticated with your organization's API key.
- **Agent** — the process inside the VM, reachable at
`https://<sandbox_id>.<sandbox-domain>/v1`. Runs commands and processes,
streams output, reads and writes files. Authenticated with a per-sandbox JWT
minted by the control plane; the API key is never sent to a sandbox.

The agent API is defined by an OpenAPI specification that each SDK vendors and
generates its low-level client from, so types stay in lockstep with the agent.
A handwritten layer on top adds retries that are safe to replay, token refresh
and incremental output streaming.

## Repository layout

```text
packages/
typescript/ @useblacksmith/sandbox (Node >= 20, ESM, no runtime dependencies)
.github/
workflows/ one workflow per package; each runs only when its package changes
```

## Status

The sandbox API is in preview. The agent API is stable; the control-plane API
(`/api/v1/sandboxes`) may still change, and each SDK isolates it behind a small
adapter so the rest of the library is unaffected. Expect breaking changes before
1.0.

## Contributing

The TypeScript SDK is developed in [useblacksmith/web](https://github.com/useblacksmith/web) (`packages/sandbox-sdk`) and mirrored here by Copybara on every push to its `main`; `packages/typescript` in this repository is output. File issues here; code changes to the TypeScript SDK go to `useblacksmith/web`.
Issues and feature requests for any SDK are welcome in this repository's
[issue tracker](https://github.com/useblacksmith/sandbox-sdk/issues).

`packages/typescript` is mirrored from Blacksmith's internal monorepo on every
push and is not edited here directly; pull requests against it will be ported
rather than merged. Everything else in this repository (this README, CI, other
language packages) is maintained in place.

## License

[MIT](./LICENSE)
Empty file added packages/typescript/.gitkeep
Empty file.