Trickest SDK
Build on Trickest from TypeScript with @trickest/sdk — typed services, pagination, agent sessions, and Live Table queries.
On this page8
@trickest/sdk is the typed TypeScript client for the Trickest platform. You construct one
TrickestClient, then reach the whole API through 21 lazy-loaded service namespaces:
spaces, workflows, runs, database (Live Tables + TQL), storage, variables, agent sessions,
memory, skills, fleet, and more.
The SDK targets Node 22+, ships as ESM and CJS, uses native fetch (edge-safe), and
depends only on Zod for optional response validation.
Install
npm install @trickest/sdk
# or: bun add @trickest/sdkGitHub Packages scope — add to .npmrc next to your project:
@trickest:registry=https://npm.pkg.github.comFull install notes: Installation.
Authenticate
import { TrickestClient } from '@trickest/sdk'
const client = new TrickestClient({
token: process.env.TRICKEST_TOKEN, // or pass token: '…' directly
baseUrl: 'https://trickest.io', // or TRICKEST_BASE_URL
})- Token:
options.token→TRICKEST_TOKENenv → constructor throws if missing. - Auth header: JWT-shaped tokens (contain
.) →Bearer; API tokens →Token. - WebSocket:
wsUrlorTRICKEST_WS_URLfor agent realtime (oftenws://localhost:3002in local dev).
See Client setup for RequestOptions, idempotency keys, and client.http.
The mental model
Service namespaces
client.spaces, client.workflows, client.runs, … — each namespace maps to REST routes under /api/.
list vs listPage
Most resources support for await (… of client.*.list()) auto-pagination or listPage() for one page.
Typed errors
Failed calls throw AuthError, NotFoundError, RateLimitError, … — branch with instanceof.
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 | Sandboxed dev sessions |
solutions | Solutions and datasets |
fleet | Fleets and machines |
users | Users, teams, roles, invites |
integrations | Docker registry integrations |
billing / audit / notifications | Org operations |
Quick start
const client = new TrickestClient()
for await (const space of client.spaces.list()) {
console.log(space.name, space.id)
}
const workflow = await client.workflows.create(spaceId, { name: 'Recon' })
const run = await client.runs.execute(workflow.id, {
inputs: { domain: 'example.com' },
})
let current = run
while (current.status === 'RUNNING' || current.status === 'PENDING') {
await new Promise((r) => setTimeout(r, 5000))
current = await client.runs.get(run.id)
}How this section is organized
CLI parity
The SDK and trickest CLI expose the same platform. Use the CLI
for shell scripts and agents in a sandbox; use the SDK for TypeScript apps, benches, and
automation (@trickest/bench is built on this client).
Agent integrations
Claude Code, Cursor, Codex, and custom agents can reach Trickest through several surfaces: the SDK for typed TypeScript, the CLI for shell automation, MCP for tool calls, and skills for repeatable playbooks. See Agent integrations for the setup paths and caveats.