---
title: "Trickest SDK"
canonical: https://trickest.com/docs/developer-tools/sdk
description: "Control workflows, runs, agent conversations, and platform data from TypeScript with @trickest/sdk."
---

# Trickest SDK

Use **`@trickest/sdk`** to control Trickest from TypeScript. Create a
`TrickestClient` to manage workflows, execute runs, query Live Tables, and work
with agent conversations. Its service namespaces group methods by resource,
such as `client.workflows` and `client.database`.

The HTTP client supports
**Node 18+**, ships as ESM and CJS, and uses native `fetch` with **Zod** for
optional response validation. Agent realtime needs a WebSocket implementation;
Node 22+ supplies one. Keep token-bearing SDK calls on the server. Agent turns use
**`SessionHandle`** to follow conversation state and **`runTurn`** to send a
prompt and wait for its result. See
[Sessions & Agent](/docs/developer-tools/sdk/sessions).

## Choose your SDK

Use **Trickest SDK** (`@trickest/sdk`) to control platform workflows, runs, agent
conversations, and data. The pages in this menu document `TrickestClient` and
its service namespaces.

Use the separate **[Sandbox SDK](/docs/developer-tools/sandbox-sdk)**
(`@trickest/sandbox`) to create a Linux environment for your own agent, execute
commands, manage files, and preview apps. It has its own documentation menu,
client, and lifecycle.

The `client.sandbox` namespace below remains part of the Trickest SDK. It manages
[workflow-linked platform sessions](/docs/developer-tools/sdk/sandbox); use
`Sandbox.create()` from the Sandbox SDK for standalone environments.

## Install

```bash
npm install @trickest/sdk
# or: bun add @trickest/sdk
```

Full install notes: **[Installation](/docs/developer-tools/sdk/installation)**.

## Authenticate

```ts
import { TrickestClient } from "@trickest/sdk";

const client = new TrickestClient({
  token: process.env.TRICKEST_TOKEN, // keep tokens in the server environment
  baseUrl: "https://trickest.io", // or TRICKEST_BASE_URL
});
```

- **Token:** `options.token` → `TRICKEST_TOKEN` env → constructor throws if missing.
- **Auth header:** JWT-shaped tokens (contain `.`) → `Bearer`; API tokens → `Token`.
- **WebSocket:** `wsUrl` or `TRICKEST_WS_URL` for agent realtime (defaults to a value derived from `baseUrl`).

See **[Client setup](/docs/developer-tools/sdk/client-setup)** for `RequestOptions`, idempotency keys, and `client.http`.

## The mental model

<CardGroup cols={3}>
  <Card title="Service namespaces" icon="layer-group">
    `client.spaces`, `client.workflows`, `client.runs`, …; each namespace maps
    to REST routes under `/api/`.
  </Card>
  <Card title="list vs listPage" icon="list">
    Most resources support `for await (… of client.*.list())` auto-pagination or
    `listPage()` for one page.
  </Card>
  <Card title="Typed errors" icon="circle-exclamation">
    Failed calls throw `AuthError`, `NotFoundError`, `RateLimitError`, …; branch
    with `instanceof`.
  </Card>
</CardGroup>

### Namespace map

| Namespace                             | Covers                                                                                       |
| ------------------------------------- | -------------------------------------------------------------------------------------------- |
| `spaces`                              | Workspaces (`/api/workspaces`)                                                               |
| `projects`                            | Projects inside a space                                                                      |
| `workflows`                           | Workflow CRUD, copy, move, versions                                                          |
| `runs`                                | Execute workflows, outputs, subjobs                                                          |
| `schedules`                           | Scheduled runs                                                                               |
| `library`                             | Public tools, scripts, modules, node resolution                                              |
| `database`                            | Live Tables, TQL, row CRUD                                                                   |
| `storage`                             | Vault file storage                                                                           |
| `variables` / `secretVariables`       | Config vs secrets (separate APIs)                                                            |
| `sessions`                            | Agent sessions, tasks, `SessionHandle`                                                       |
| `memory` / `skills`                   | Agent memory and skills                                                                      |
| `sandbox`                             | Platform sandbox sessions; [current compatibility limits](/docs/developer-tools/sdk/sandbox) |
| `solutions`                           | Solutions and datasets                                                                       |
| `fleet`                               | Fleets and machines                                                                          |
| `users`                               | Users, teams, roles, invites                                                                 |
| `integrations`                        | Docker registry integrations                                                                 |
| `billing` / `audit` / `notifications` | Org operations                                                                               |

## Quick start

Choose a saved workflow with configured inputs and available fleet capacity.
Creating workflow metadata alone does not create a runnable graph. This example
starts a run in your account.

```ts
import { TrickestClient } from "@trickest/sdk";

const client = new TrickestClient();
const workflowId = process.env.TRICKEST_WORKFLOW_ID;
if (!workflowId)
  throw new Error("Set TRICKEST_WORKFLOW_ID to a saved workflow");

const workflow = await client.workflows.get(workflowId);
const run = await client.runs.execute(workflow.id);
const finished = await client.runs.waitFor(run.id, { timeoutMs: 600_000 });
console.log(finished.status);
if (finished.status !== "COMPLETED") {
  throw new Error(`Run ended with status ${finished.status}`);
}
```

Check nested and distributed job results, plus expected output files, before
treating a run as successful. The final run status alone is not enough.

## Documentation map

<CardGroup cols={2}>
  <Card
    title="Getting Started"
    icon="rocket"
    href="/docs/developer-tools/sdk/installation"
  >
    Install, client options, errors, pagination, retries.
  </Card>
  <Card
    title="Workflows"
    icon="diagram-project"
    href="/docs/developer-tools/sdk/spaces-projects"
  >
    Spaces, projects, workflows, runs, schedules.
  </Card>
  <Card title="Agent" icon="robot" href="/docs/developer-tools/sdk/sessions">
    SessionHandle, runTurn, memory, skills.
  </Card>
  <Card
    title="Agent integrations"
    icon="code-branch"
    href="/docs/developer-tools/sdk/agent-integrations"
  >
    Connect Claude Code, Cursor, Codex, custom agents, and sandboxes through
    SDK, CLI, MCP, and skills.
  </Card>
  <Card
    title="Data & Assets"
    icon="database"
    href="/docs/developer-tools/sdk/database"
  >
    Live Tables (TQL), storage, variables, library, solutions.
  </Card>
  <Card
    title="Organization"
    icon="building"
    href="/docs/developer-tools/sdk/fleet"
  >
    Fleet, users, integrations, billing.
  </Card>
  <Card
    title="Method index"
    icon="list"
    href="/docs/developer-tools/sdk/method-index"
  >
    Find methods by service namespace.
  </Card>
</CardGroup>

## Use the CLI from a terminal

The SDK and [`trickest` CLI](/docs/developer-tools/cli) expose the same platform. Use the CLI
for shell scripts and agents in a sandbox; use the SDK for TypeScript apps and
automation.

## Agent integrations

Claude Code, Cursor, Codex, and custom agents can connect to Trickest through
the SDK for typed TypeScript, the CLI for shell automation, MCP for tool calls, and skills
for repeatable playbooks. See **[Agent integrations](/docs/developer-tools/sdk/agent-integrations)**
for setup instructions and limits.

---
_Markdown source of https://trickest.com/docs/developer-tools/sdk._