Documentation
Duct Documentation
Build one permissioned product surface for humans and agents. Start with the quickstart, then wire actions, auth, embedding, and API access in the language your system already uses.
SDK & CLI — start here
Most integrations begin with four commands. Run them from your product repo root (Node.js 20+).
Official npm package — CLI, typed manifest helpers, and framework adapters for Node.js 20+.
$ npm i @duct-sdk/sdkDuct is not TypeScript-only
The published SDK is TypeScript/JavaScript because it ships the CLI and web adapters. Your backend can be Python, Go, Ruby, Java, PHP, .NET, or anything else that can expose HTTP endpoints and verify JWTs. Agents can call Duct through REST with curl, Python, JavaScript, or any HTTP client.Recommended Path
Quickstart
Create, configure, push, and test a shell.
CLI & SDK
login, init, push, scan, rollback — terminal commands for every integration step.
Frameworks & Languages
TypeScript SDK, JavaScript, Python, curl, and any HTTP backend.
Configuration
The manifest fields that define actions, routes, auth, and UI.
Action Permissions
agentAccessible, sideEffects, sensitivityLevel — what to set and what happens at runtime.
Embed The Shell
Add Duct to Next.js, React, or plain JavaScript apps.
REST API
Use Duct from Python, JavaScript, shell scripts, or agents.
Agent Access
How AI agents securely act on your product’s behalf — tokens, profiles, and user consent.
Inter-Shell Protocol
Open discovery, runtime consent, and scoped delegation between shells.
Threat Model
Trust boundaries, tokens, IS-* invariants, SSRF, and prompt-injection posture.
Deeplinks
Signed navigation handoffs back into your product.
Reference
Terminology, permissions, and common questions.
AI Integration Prompt
One-file prompt for your AI coding assistant to generate or audit a complete Duct integration.
What You Build
A Duct integration has four moving parts: a manifest that describes your product capabilities, a small widget embed, token endpoints for user-aware actions, and optional agent API calls for automation.
Human shell
An in-product chat surface that can answer, show UI, ask for confirmation, and navigate users.
Agent API
A structured REST surface that lets approved agents invoke the same actions under the same permissions.
Manifest
duct.config.ts — product, routes, widget, and deeplinks.
Action permissions
What to set on each action and how Duct enforces agentAccessible, sideEffects, and sensitivity.
Deeplink receiver
A route in your app that verifies signed handoff tokens and restores state.
AI integration prompt
One file — paste into your AI coding assistant to generate or audit a full integration.
Common Questions
How does shell-to-shell work?
Open discovery via capability search. Your user's message triggers a network search; the user consents in-chat before any cross-shell action runs. No pre-configuration between companies required. See the Inter-Shell Protocol docs for details.
Can any shell call mine?
Only if you set registry_visibility: 'public' and intershell_enabled: true. By default shells are private. You can further restrict with allowedCallers to limit inbound calls to a specific list of shell IDs.
If I add side effects to an existing action, is fresh consent required?
Yes — always, on the next invocation. Changing sideEffects from false to true means the action now requires confirmation every time it runs. Prior read-only calls in the same chat do not count as consent. See manifest versions & side-effect changes.