@boatdev/sdk

Use Boat from your application code.

Install

npm install @boatdev/sdk

Links

• SDK docs: https://docs.boat.dev/sdks/overview
• API reference: https://docs.boat.dev/api/v1
• Dashboard: https://boat.dev/dashboard
• API keys: https://boat.dev/dashboard?tab=api-keys

Flow

1. Create an API key in the Boat dashboard.
2. Create or resume a sandbox.
3. Prompt the sandbox.
4. Read events until the work is done.
5. Open desktop access when you need browser or GUI visibility.
6. Stop, resume, fork, or delete the sandbox according to your retention policy.

Notes

• Put cleanup in finally: stop/archive or delete sandboxes you create for tests.
• Treat API key secrets, Boat secrets, SSH keys, and desktop stream URLs as sensitive.
• updateSecrets / update_secrets replaces the entire secret setup. Read the current setup first and send every env var and secret file that should remain.
• rotateApiKey / rotate_api_key rotates the raw secret in place. Store the returned secret immediately; it is shown once.
• Repository selection is idempotent. Selecting an already-selected repository updates its base branch.

Example

TypeScript

import { BoatApi, Configuration } from "@boatdev/sdk";

const sandbox = new BoatApi(new Configuration({
  basePath: process.env.BOAT_BASE_URL ?? "https://boat.dev/api/v1",
  accessToken: process.env.BOAT_API_KEY ?? (() => {
    throw new Error("Set BOAT_API_KEY from the Boat dashboard API keys tab.");
  })(),
}));

async function main() {
  let sandboxId: string | undefined;

  try {
    const created = await sandbox.create({ ttlSeconds: 1800 });

    sandboxId = created.sandbox.id;

    await sandbox.update({ sandboxId, name: "sdk-demo" });

    while (!["ready", "idle"].includes((await sandbox.get({ sandboxId })).sandbox.state)) {
      await new Promise((resolve) => setTimeout(resolve, 2000));
    }

    await sandbox.prompt({
      sandboxId,
      prompt: "Inspect the repository and summarize the test command.",
      provider: "codex",
    });

    const events = await sandbox.events({ sandboxId });
    console.log(events.events);
  } finally {
    if (sandboxId) {
      await sandbox.stop({ sandboxId });
    }
  }
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

JavaScript

const { BoatApi, Configuration } = require("@boatdev/sdk");

const sandbox = new BoatApi(new Configuration({
  basePath: process.env.BOAT_BASE_URL || "https://boat.dev/api/v1",
  accessToken: process.env.BOAT_API_KEY || (() => {
    throw new Error("Set BOAT_API_KEY from the Boat dashboard API keys tab.");
  })(),
}));

async function main() {
  let sandboxId;

  try {
    const created = await sandbox.create({ ttlSeconds: 1800 });

    sandboxId = created.sandbox.id;

    await sandbox.update({ sandboxId, name: "sdk-demo" });

    while (!["ready", "idle"].includes((await sandbox.get({ sandboxId })).sandbox.state)) {
      await new Promise((resolve) => setTimeout(resolve, 2000));
    }

    await sandbox.prompt({
      sandboxId,
      prompt: "Inspect the repository and summarize the test command.",
      provider: "codex",
    });

    const events = await sandbox.events({ sandboxId });
    console.log(events.events);
  } finally {
    if (sandboxId) {
      await sandbox.stop({ sandboxId });
    }
  }
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

License

This SDK is MIT licensed. Boat, the Boat API, the Boat CLI, and the sandbox product are proprietary.