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 18+, ships as ESM and CJS, uses native fetch (edge-safe), and
depends only on Zod for optional response validation. Agent turns use
SessionHandle (projection-first) and the runTurn helper. See
Sessions & Agent.
Install
npm install @trickest/sdk
# or: bun add @trickest/sdkFull 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 (defaults to a value derived frombaseUrl).
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: 'Discovery' })
const run = await client.runs.execute(workflow.id, {
inputs: { domain: 'example.com' },
})
const finished = await client.runs.waitFor(run.id, { timeoutMs: 600_000 })
console.log(finished.status)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 and
automation.
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.