LanguageEN繁
Home
Docs

Host and Connect

Host Heddle in the product you already have

Heddle owns durable conversation and run mechanics without requiring your product to adopt a specific server framework, transport, identity provider, database, or UI.

Customization depth

Advanced lifecycle

Hosting depth

Choose by host assumptions

Documentation status

Supported SDK boundary

Assumptions

  • Your agent runtime runs in a Node.js 20+ TypeScript/ESM host.
  • Your product can provide a stable conversation ID and decide who may access it.
  • You want to preserve your existing API, authentication, state, and frontend choices.
Heddle owns
  • Persisted conversations, turns, compaction, leases, traces, artifacts, tools, and approvals.
  • Addressable run identity, ordered activity, bounded replay, explicit cancellation, and terminal settlement when the hosted layer is selected.
  • Remote envelope validation, cursor rules, duplicate and gap handling, and bounded reconnect calculation when the remote package is selected.
Your product owns
  • Identity, tenancy, authorization, stable product conversation IDs, and access policy.
  • Server framework, routes or procedures, public schemas, errors, CORS, limits, audit, and deployment.
  • UI state, messages, tool presentation, retry UX, notifications, and application of final results.

Two independent choices

Heddle's public surfaces separate customization depth from hosting assumptions. You can use the full conversation engine inside one process without exposing a network API, or add hosted and remote layers without replacing the product behavior you already built.

The dependency direction should remain:

Text
Product UI and client state
        |
@roackb2/heddle-remote + optional HTTP/SSE client
        |
Your transport adapter, authentication, and public schemas
        |
Your application service and composition root
================ HEDDLE SDK BOUNDARY ================
ConversationRunService
        |
ConversationEngine
        |
Models, tools, host extensions, and MCP

The application-service layer above the boundary is still your code. It maps authenticated product identity to stable conversation IDs, constructs the engine with product tools and credentials, and decides which internal data may become public output.

Choose the lowest matching layer

What your product already hasStart withSupport level
A TypeScript process and no agent UIrunQuickstartConversationCliSupported SDK entrypoint
Its own local output or lifecyclecreateConversationEngine from @roackb2/heddleSupported SDK entrypoint
A server, worker, or Electron backendConversationRunService from @roackb2/heddle/hostedSupported and runnable
Express with REST and SSE@roackb2/heddle/hosted/http-sseSupported helper and runnable Express reference
A remote JavaScript client over any transport@roackb2/heddle-remoteSupported transport-neutral package
A browser using the conventional REST/SSE contract@roackb2/heddle-remote/http-sseSupported and runnable
A React/Vite frontendHosted React exampleRunnable reference product, not a React SDK
tRPC, Fastify, Hono, Nest, WebSocket, IPC, or queuesHosted service plus your adapterAdaptation guide
Multi-process or serverless executionHosted service plus shared routing or deliveryArchitecture guidance

Do not install Express or React only because a reference example uses them. Stop at the transport-neutral hosted service when your product already has another server or client architecture.

The durable boundary

A conversation is durable state. A run is one addressable execution against that conversation. Keeping them separate lets an HTTP request return after accepting a run while the model and tools continue, clients disconnect and reconnect without restarting work, and a later turn reuse the same persisted conversation.

Use one stable Heddle session ID for each product conversation. Do not replay a separate product transcript into every prompt, create a second host-side run ID, or add another in-process event bus around Heddle's run stream. Those parallel paths create conflicting sources of truth.

Continue by need

  • Choose Long-lived run service when work must outlive one request or needs cancellation, approvals, and reconnectable subscribers.
  • Choose Node HTTP/SSE when the conventional REST/SSE contract matches your server.
  • Choose Remote client when untrusted events cross a network boundary.
  • Read Adapt another stack before translating the lifecycle to an existing framework.
  • Complete the Production checklist before treating a reference example as a deployed service.

Canonical sources