Documentation

Quickstart

Create a shell, write a manifest, push it to Duct, and test the widget. This path is designed for a developer to follow from zero to a working integration.

Commands used in this guide

Each step below maps to one CLI command. Keep the full reference open while you integrate.

$ npx @duct-sdk/sdk login
$ npx @duct-sdk/sdk init --manual
$ npx @duct-sdk/sdk push
$ npx @duct-sdk/sdk checkup

Full CLI reference →

@duct-sdk/sdk

Official npm package — CLI, typed manifest helpers, and framework adapters for Node.js 20+.

npm packageSDK imports
$ npm i @duct-sdk/sdk

Prerequisites

1

Duct account

Get early access — we'll provision your workspace when approved.
2

A web app or API

Duct works with any app that can expose HTTP endpoints. The SDK is TypeScript, but the runtime integration is HTTP.
3

Node.js for the CLI

Use Node.js 20+ to run the CLI via npx, pnpm dlx, or yarn dlx.

Login

bash
npx @duct-sdk/sdk login

This stores your Duct API key locally so the CLI can push manifests to your workspace.

Generate A Starter Manifest

bash
npx @duct-sdk/sdk init --manual

Manual init is the reliable first path. It creates a readable duct.config.tsthat you edit directly. You can later use init, init --update, or init --api-spec / init --curl-collection to import from existing API docs.

Fill In The Manifest

Define the product, user-facing routes, callable actions, auth strategy, and widget behavior.

ts
import { defineDuctConfig } from '@duct-sdk/sdk';

Review every action

Read-only actions can usually be agentAccessible: true with sideEffects: false and sensitivityLevel: low. Mutations, billing, auth, deletion, and high-sensitivity data should stay locked down unless you have a clear consent path. See the Action Permissions for concrete values and runtime behavior.

Push To Duct

bash
npx @duct-sdk/sdk push

After push, your hosted shell is available at:

bash
https://shell.ductai.vercel.app/{shellId}

Token route — use the /server import on the backend

When wiring the token endpoint in Node.js, Express, Remix loaders, or Next.js API routes, import from @duct-sdk/sdk/server — not the root package. The root export includes React adapters which crash runtimes where React is not installed. import { generateDuctToken } from "@duct-sdk/sdk/server"

Wire Middleware And Embed

After init, copy the snippet from .duct/snippets/verify-duct-token.ts into your API auth middleware so proxied action calls authenticate. Then add the generated shell component to your root layout.

tsx
'use client';

Verify And Test

Run npx @duct-sdk/sdk checkup to re-run service connectivity checks and the integration audit (token route, receiver, embed, env, deeplinks). Then exercise chat, actions, confirmation, and deeplinks in your app.

bash
npx @duct-sdk/sdk checkup

Test Checklist

  • Ask a natural-language question about your product.
  • Ask for a read-only data action, such as "show my open orders".
  • Try a side-effect action and confirm that Duct asks for confirmation.
  • Trigger a deeplink and confirm the receiver route restores state.
  • Open dashboard Analytics after signing in; expand a recent session and use Open audit to jump to Conversations with the full turn trace and permission chain.
  • Run npx @duct-sdk/sdk checkup until the integration audit has no blocking errors.