LanguageEN繁
Home
Docs

Start here · Prerequisites

Install Heddle and configure a model

Prepare a Node.js 20+ TypeScript/ESM host and one model credential before running the SDK examples.

Customization depth

Level 1 — Working conversation

Hosting depth

A — Node.js process

Documentation status

Supported SDK boundary

Assumptions

  • Node.js 20 or newer
  • A TypeScript/ESM application or evaluation project
  • Server-side or local-process execution; the main Heddle package is not a browser package
Heddle owns
  • Provider routing and credential preflight
  • Conversation defaults and local persisted state
Your product owns
  • Credential provisioning and secret storage
  • Model choice, cost policy, and provider account

Install the runtime package

Shell
npm install @roackb2/heddle

The curated package contains the quickstart runner, conversation engine, tools, MCP host extensions, approvals, sessions, artifacts, and host-facing result types.

If a browser will consume a remotely hosted Heddle agent later, install the browser-safe package in the client application instead:

Shell
npm install @roackb2/heddle-remote

Do not bundle @roackb2/heddle into a browser client. It is the Node runtime.

Configure one provider

OpenAI Platform API key

Shell
export OPENAI_API_KEY="your_key"

Platform API-key authentication is the stable OpenAI path for embedded products. Heddle also offers experimental, user-selected OpenAI account sign-in through the CLI, but an application should not treat a consumer account session as its production credential design.

Anthropic API key

Shell
export ANTHROPIC_API_KEY="your_key"

Heddle does not use Anthropic consumer-subscription OAuth. Supply an API key when selecting a Claude model.

Local Ollama model

Start Ollama, list the locally installed models, and select one with the ollama/ prefix:

Shell
ollama list
export HEDDLE_MODEL="ollama/llama3.2:latest"

Local model compatibility does not guarantee reliable tool calling. Validate the exact model against your tools and product workflow.

Select a model

The quickstart resolves the first configured value from HEDDLE_MODEL, HEDDLE_EXAMPLE_MODEL, OPENAI_MODEL, or ANTHROPIC_MODEL, then uses Heddle's built-in OpenAI default.

For explicit product composition, pass the model when creating the engine:

TypeScript
import { createConversationEngine } from '@roackb2/heddle'

const engine = createConversationEngine({
  workspaceRoot: process.cwd(),
  stateRoot: process.cwd() + "/.heddle",
  model: process.env.HEDDLE_MODEL ?? "gpt-5.4",
  preferApiKey: true,
})

preferApiKey keeps embedded-product composition on the Platform API-key path even when the machine also has an experimental CLI account session. A host that resolves credentials itself may pass apiKey directly instead.

Avoid copying a long model list into application code. Use the models and credentials reference for provider prefixes and current setup details.

Checkpoint

Your host is ready when it can import @roackb2/heddle, resolve one supported model, and access the matching credential without exposing that credential to browser code.

Continue to Build your first agent, or use Choose an integration layer if your product already owns a server or UI.

Canonical sources