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

# Use a sandbox from TypeScript

> Install the TypeScript SDK, create a sandbox, run a command, write files, connect with SSH, and delete the sandbox.

In this tutorial, you use the TypeScript SDK to create a sandbox, run a command in it, write files, open SSH, and delete the sandbox.

Write a script that uses a sandbox with the TypeScript SDK.

Use @vms.dev/sdk. Create a Vms client that reads VMS\_API\_KEY.
Create a small sandbox with vms.createSandbox, then call vms.waitUntilRunning.
Run a command with vms.exec and print the events while it runs.
Write files with vms.writeFiles, and delete the sandbox at the end.
Do not ask me to share my API key.

## Before you start

* Your workspace needs a plan or a trial. See [Choose a plan or start a trial](https://vms.dev/docs/workspace/billing.md).
* You need an API key with the `sandboxes:read`, `sandboxes:write`, `sandboxes:exec`, `sandboxes:files`, and `sandboxes:ssh` scopes. See [API keys](https://vms.dev/docs/workspace/api-keys.md).
* You need Bun to run the script.
* For the SSH step, you need OpenSSH and an SSH key in `~/.ssh/id_ed25519`. To make a key, run `ssh-keygen -t ed25519`.

**1. Install the SDK**

Install the package, and put your API key in the `VMS_API_KEY` environment variable.

```bash theme={null}
bun add @vms.dev/sdk
export VMS_API_KEY="<your-api-key>"
```

**2. Create a sandbox and wait until it runs**

Save this code in `sandbox.ts`. `waitUntilRunning` reads the sandbox until its state is `running`.

```typescript TypeScript theme={null}
import { Vms } from "@vms.dev/sdk";

const vms = new Vms();

const created = await vms.createSandbox({
  body: { size: "small", name: "my-first-sandbox" },
  idempotencyKey: crypto.randomUUID(),
});

const sandbox = await vms.waitUntilRunning(created.id);

console.log(sandbox.id, sandbox.state);
```

**3. Run a command**

Add this code. `exec` gives each event of the command while it runs. `wait` gives the full output and the exit code.

```typescript TypeScript theme={null}
const run = await vms.exec(sandbox.id, "uname -a && ls /home/user");

for await (const event of run) {
  if (event.type === "stdout") process.stdout.write(event.data);
}

const result = await run.wait();

console.log("exit code", result.exitCode);
```

**4. Write files**

Add this code. `writeFiles` sends all files in one tar upload.

```typescript TypeScript theme={null}
await vms.writeFiles(sandbox.id, [
  { path: "/home/user/app/index.js", content: 'console.log("hello");\n' },
  { path: "/home/user/app/run.sh", content: "#!/bin/sh\nnode index.js\n", mode: "0755" },
]);

const output = await vms.exec(sandbox.id, "./run.sh", { cwd: "/home/user/app" });

console.log((await output.wait()).stdout);
```

**5. Connect with SSH**

Add this code. `ssh` adds your public key to the sandbox, then runs `ssh` with the host key of `ssh.vms.dev`. Leave out `command` to open a shell.

```typescript TypeScript theme={null}
const ssh = await vms.ssh(sandbox.id, {
  command: "hostname",
  stdio: "pipe",
});

console.log(ssh.stdout);
```

**6. Delete the sandbox**

Add this code, then run `bun sandbox.ts`.

```typescript TypeScript theme={null}
await vms.deleteSandbox({ id: sandbox.id });
```

## Check the result

The script prints the sandbox ID and `running`, the output of `uname -a`, `exit code 0`, `hello`, and the name of the sandbox. Then the script deletes the sandbox.

If a call fails, the SDK throws a `VmsError` with the HTTP `status` and the error `code`, such as `no_capacity`. See the [SDK reference](https://vms.dev/docs/reference/typescript-sdk.md#errors).

## Next steps

* [TypeScript SDK reference](https://vms.dev/docs/reference/typescript-sdk.md)
* [Run commands in a sandbox](https://vms.dev/docs/sandboxes/run-commands.md)
* [Stop and resume a sandbox](https://vms.dev/docs/sandboxes/stop-and-resume.md)

Read the [changelog.](https://vms.dev/docs/changelog.md)


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