---
title: Device and agent SDK
description: Use one owner-issued SDK token to connect agents and attach devices, with separate owner approval for each device function.
---

The openlaunch SDK connects agents to devices through one bridge token. That token can authenticate an agent and, when enabled by the owner, attach devices to the workspace. Attaching a device does not grant the agent permission to use its functions; the owner approves those separately.

## Make a token

In the console, open **Connections** and create a named SDK token. Choose read or action access, set an expiry, and enable device attachment with a limit from 1 to 20 devices if the token will pair hardware. The default is one device for seven days. Copy the token when it appears; it is shown once. Save it in a secret manager or environment variable. Do not put it in source code, prompts, shell history, or logs.

Revoke a token in **Connections** to stop agent requests and future device attachments. Devices already attached remain paired until you remove them from **Devices**. Per-device function grants are separate and can also be revoked or allowed to expire.

## Connect an agent

Install the SDK from the hosted archive:

```sh
npm install https://www.openlaunch.dev/downloads/openlaunch-sdk.tgz
```

Read the token from a private environment variable and create a client:

```ts
import { createClient } from "@openlaunch/sdk";

const openlaunch = createClient({
  url: "https://www.openlaunch.dev",
  token: process.env.OPENLAUNCH_SDK_TOKEN!,
});

const devices = await openlaunch.listDevices();
const device = devices[0];
if (!device) throw new Error("No devices are granted to this agent");

const action = await openlaunch.requestAction(device.id, {
  capability: "device.health",
  idempotencyKey: crypto.randomUUID(),
});

let result = action;
while (["queued", "received"].includes(result.status)) {
  await new Promise((resolve) => setTimeout(resolve, 1_000));
  result = await openlaunch.getAction(action.id);
}
console.log(result.status, result.result);
```

Choose action access for this example; a read token can list devices and inspect actions but cannot request them. Device grants still decide which functions the agent can use. A queued action is not a completed action; check the final result. See [Connect an agent](/docs/agents) for MCP clients and other connection options.

Use `cancelAction(id)` before a device receives an action. `broadcast({ deviceIds, capability, arguments, idempotencyKey })` requests the same function from several devices and returns a result per device. Retry a request with the same idempotency key only when its arguments are identical. Agents written in other languages can use the same HTTP endpoints with `Authorization: Bearer <SDK token>`; see the [API reference](/docs/api).

## Attach a device with one command

For a Linux machine, gateway or Node adapter, open **Devices → Add device** and choose **Create a new one-device token**. Give it a name and expiry, then select **Create token and continue**. The console shows the one-time token and a setup command. Copy the command and run it on the machine beside your hardware:

```sh
npx --yes --package=https://www.openlaunch.dev/downloads/openlaunch-sdk.tgz openlaunch-device setup --url https://www.openlaunch.dev
```

The command asks only for the SDK token, with the input hidden. It gets the workspace from the token, creates a starter adapter, saves a private per-device credential, and starts polling. It never saves the SDK token. If setup loses its connection, rerun the same command with the same token within 10 minutes to resume the saved request.

After the device appears, the console opens its **Access** view. Choose which functions the agent connection may use and set a grant expiry. The starter reports the adapter process health; connect your hardware library and implement its functions in `adapter.mjs` to control real hardware.

Change and publish the function list with:

```sh
npx --yes --package=https://www.openlaunch.dev/downloads/openlaunch-sdk.tgz openlaunch-device publish
```

Then approve the published functions in the console and restart the adapter:

```sh
npx --yes --package=https://www.openlaunch.dev/downloads/openlaunch-sdk.tgz openlaunch-device run
```

Publishing a changed manifest clears earlier grants and cancels queued actions. It cannot undo a command already delivered to a device.

## Use the SDK directly

The same token can attach a device from JavaScript or TypeScript. Use a stable UUID request ID for retries of the same attachment and manifest:

```ts
import { createDevice } from "@openlaunch/sdk";

const device = createDevice({
  url: "https://www.openlaunch.dev",
  token: process.env.OPENLAUNCH_SDK_TOKEN!,
});
const identity = await device.attach(manifest, crypto.randomUUID());
// Store identity.deviceId and identity.token in protected device storage.
```

`createDevice()` uses the SDK token only to attach; the device polls with the private child credential. The SDK keeps credentials in memory, so store the returned device identity securely if the process must restart. `nextAction()` retrieves one action and `submitResult()` reports its outcome.

## Bring another board

Use the Node adapter beside the board, or implement the same HTTPS attach, poll and result flow in firmware. A custom device kind such as `custom.rp2040` does not need a built-in board profile. Declare only the functions your adapter implements, using bounded input fields. A manifest is a description and input schema; it does not install firmware or create hardware support.

The maintained integrations are Uno R4 WiFi and Raspberry Pi. Their real board behavior is still subject to the hardware checks in the [verification guide](/docs/status). See [Build your own functions](/docs/functions) for input and permission rules, and the [API reference](/docs/api) for request routes.

The former one-use enrollment flow remains available for existing integrations. New agent and device connections should use the SDK token flow above.

## Standalone ESP32

The [ESP32 Arduino library](/downloads/openlaunch-esp32.zip) includes a health example and portable C++ SDK. Download the [USB provisioner](/downloads/provision-esp32.py) and verify it against the checksum in [`installers.json`](/downloads/installers.json). After uploading the firmware, configure the board over USB:

```sh
python3 provision-esp32.py --port /dev/cu.YOUR_CONFIRMED_PORT --origin https://www.openlaunch.dev
```

The helper prompts for Wi-Fi details and an SDK token with hidden input, then asks before sending settings. It does not ask you to edit a `secrets.h` file or flash firmware. The hosted origin uses a bundled, fingerprint-checked public CA. For another origin, supply its trusted public root certificate with `--ca-file`. The archive is compile-verified; physical ESP32 operation remains unverified. See [downloads and resources](/docs/resources).