Documentation

Reference

Common terms and decisions you will see while building a Duct integration.

Core Terms

Shell
A permissioned execution surface backed by an action manifest — the hosted Duct interface for one product or environment. Humans use the embedded widget; agents call the invoke API. One manifest enforces both.
Manifest
Your product capability contract: actions, routes, auth, deeplinks, permissions, and widget settings.
Action
A product API operation that Duct may invoke after policy and auth checks.
Route
A user-facing page in your app that Duct can describe or navigate to.
Deeplink
A signed navigation handoff from the shell to your app with state.
Shell token
A token proving an agent or service owns a Duct shell.
User consent token
A delegated token representing a real user session for user-scoped actions.
Side effect
Any action that changes data, sends data, charges money, deletes, creates, or triggers work.

Permission Rules

Per-field values, caller matrices, scenario checklist, and invoke error codes: Action Permissions. Manifest file layout: Configuration.

Read-only data
Low sensitivity, user-scoped GETs — usual candidates for agentAccessible true.
Mutations
sideEffects true; human ConfirmCard; agents need consent + 202 per call.
Auth-required
requiresAuth true; agents pass user_consent_token; guests blocked.
High sensitivity
Treat as PII/financial; tighten agentAccessible and sensitivityLevel.

SDK Import Guide

The SDK ships three kinds of exports. Use the right one to avoid pulling React into Node.js backends or pulling the CLI agent code into a browser bundle.

@duct-sdk/sdk/server
Backend-safe: token helpers, config, introspect handlers. No React. Use in Express, Fastify, Next.js API routes, Remix loaders, or any Node.js/Edge runtime.
@duct-sdk/sdk/react
DuctShell and useDuctPageContext. Requires React 18+. Use in client components only.
@duct-sdk/sdk/next
DuctShell + DuctReceiver for Next.js App Router. Requires React 18+.
@duct-sdk/sdk/vite
DuctShell + DuctViteReceiver for Vite + Express.
@duct-sdk/sdk/sveltekit
DuctSvelteKitReceiver for SvelteKit hooks.
@duct-sdk/sdk (root)
Full bundle. Only use in Next.js / React SSR frontends that have React installed. Crashes plain Express backends.

FAQs

Is Duct only for TypeScript?

No. The SDK and CLI are TypeScript/JavaScript because they generate web embeds and typed configs. Your product API can be Python, Go, Ruby, Java, PHP, .NET, or any HTTP backend.

Why is the config TypeScript?

TypeScript gives autocomplete and validation for the manifest. It is a build-time authoring tool, not a runtime requirement for your backend.

Does Duct replace my API?

No. Duct sits in front of your API. You choose which actions are exposed and under what permissions.

How is Duct different from MCP?

MCP is a tool protocol. Duct is a hosted product access layer: permissions, consent, UI, deeplinks, analytics, and action execution around your existing API.

How is Duct different from support chat?

Support chat answers questions. Duct can answer, show UI, execute approved actions, and hand users into product pages.

What happens if I add side effects to an action that was read-only?

The next invocation requires fresh consent — no exceptions. After push, the live manifest marks the action as a side effect. Human users see ConfirmCard; agents get 202 confirmation_required per call. Prior successful read-only runs in the same chat session do not count as approval for the mutation. If you change what an action does (path, method, or side-effect flags), existing user consent for that action stops matching — users must approve again. Agent tokens from before the push may return MANIFEST_STALE until the agent re-exchanges its key. Full detail: manifest versions & side-effect changes.

Which CLI command do I run first?

npx @duct-sdk/sdk login, then init --manual, edit duct.config.ts, and push. See the CLI & SDK reference.

Naming convention

Use clear action names such as get_invoice, list_orders, and create_refund_request. Avoid vague names like run or submit; they are harder for agents and reviewers to reason about.