Skip to main content

Requirements

  • Node.js 22.19 or newer (engines.node in package.json, set by the undici@8 dependency, whose own engines is >=22.19.0; the other version-gated Node features it uses are node:sqlite for SqliteStore (22.13) and native type stripping for .ts agent files (22.18), both below that floor, so lowering it means relaxing the undici dependency first; undici is loaded only when the http_request or web_fetch tool makes a request, see Optional peers).
  • TypeScript is optional but recommended - the SDK ships full type definitions.

Install the package

ai (the Vercel AI SDK: ^4.3.19, ^6.0.0 or ^7.0.0) and zod (^3.25.76 || ^4.0.0) are required peer dependencies. ai 5 is not supported. Schemas from either zod major work everywhere the SDK takes one (defineTool({ input }), structured output, MCP tools), including zod 4 schemas from zod/v4 while zod 3.25 is installed and zod 3 schemas from zod/v3 on zod 4. A defineTool input can also be another Standard Schema library’s schema if it exposes its JSON Schema (~standard.jsonSchema); the model needs a JSON Schema, so a Standard Schema without one is rejected (use zod for those tools). ai 4’s provider packages declare zod 3 as a peer, so pair zod 4 with ai 6 or 7.

Provider packages

Each real LLM provider is backed by an optional peer dependency, in the major that pairs with your ai major. Install the pair from one row: For example, on the current ai major:
Ollama on ai 6/7 needs zod 4. ollama-ai-provider-v2 (the Ollama package for ai 6 and 7) declares zod ^4 as a peer. The SDK accepts zod 4, so install it with zod 4, for example npm install ai@^7.0.0 ollama-ai-provider-v2@^4.0.0 zod@^4.0.0. With zod 3, use ai@^4.3.19 with ollama-ai-provider@^1.2.0. lousho init --provider ollama scaffolds ai@^7.0.0 with ollama-ai-provider-v2@^4.0.0 and zod 4. What CI tests. Every pairing the peer ranges accept is installed for real and run through the type check, the build and the whole test suite, on every change: ai 4 with zod 3 (the dev install) and zod 4, ai 6 with zod 3 and with zod 4, and ai 7 with zod 3 and with zod 4. The two zod 4 entries on ai 6 and 7 also install ollama-ai-provider-v2 (3.x and 4.x) and run the Ollama provider against it, so Ollama on ai 6/7 is tested, not assumed. Peers are loaded on demand: importing lousho (or any of its sub-entries) never loads a provider package, so you only need to install the ones you use. Each provider package is loaded the first time that provider makes a call; if it is missing, that call fails with a MissingPeerDependencyError that carries the exact command to run, for the ai major you have installed. The vendor/ model prefix chooses the provider; with OpenRouter use openrouter/<vendor>/<model> (e.g. openrouter/openai/gpt-4o-mini). With ai 4:

Optional peers

These packages are optional peers too. A project that never uses Docker sandboxing, MCP, OpenTelemetry tracing, the React or Vue bindings, lousho build, the lousho init questions or code mode installs none of them: Like the provider packages, each is loaded on first use, never at import time, and a missing one fails that call with a MissingPeerDependencyError that names the feature and the exact command, for example:
npm create lousho installs prompts itself, so scaffolding with it needs nothing extra. lousho doctor lists every optional peer, what it enables and whether it is installed (a missing dockerode is an error only when the agent spec uses a sandboxed tool). undici and yaml stay regular dependencies. yaml parses agent specs, agent.yaml files and skills, and Node has no built-in YAML parser. undici is loaded on the first request of the http_request or web_fetch tool: both connect through an undici Agent whose DNS lookup checks the address and pins the connection to it, and http_request also scopes validateSSL: false to that Agent. The global fetch can express neither.

Package size

The tarball is about 4 MB packed (15 MB unpacked). That is a stated trade-off, not an accident: src/ ships because lousho build bundles src/deploy/runtime.worker.ts and src/index.ts from the installed package and the dist/ source maps point at it (the maps carry no embedded source; embedding it instead and dropping src/ measured larger, 5.2 MB packed). The 1 MB llms-full.txt is in the repo, not the package.

Entry points share code (ESM and CJS)

The package entries (., ./hooks, ./tools, ./mcp, …) are built with code splitting: they import shared chunks from dist/, so a class or singleton such as HookRegistry, SDKError or globalToolRegistry is the same object whichever entry that exports it you import it from, within one module format (globalToolRegistry is exported by ./executor and ./tools, not by the root). An ESM import and a CJS require of the package in one process still load two separate copies (Node’s dual-package hazard), so a class from one is not === the other. instanceof SDKError, of each SDKError subclass the SDK exports (ValidationError, TimeoutError, RateLimitError, LLMProviderError, MissingPeerDependencyError, …) and of HookRegistry are safe across the two copies (they check a Symbol.for brand); for other classes, use one module format per process. The entries exports declares, and what each one holds:

TypeScript settings

The declarations type-check with skipLibCheck: false under zod 3 and zod 4, with moduleResolution bundler, nodenext and node16 (ESM). One combination fails, and the cause is upstream: a CommonJS project (no "type": "module") with module/moduleResolution: "node16" and ai 7. ai 7 ships ES modules only, and TypeScript’s node16 mode does not let CommonJS code import those types (error TS1479 inside the SDK’s declarations). Use "module": "nodenext" (it resolves them) or "moduleResolution": "bundler", add "type": "module", or keep skipLibCheck: true (what lousho init projects use). The root entry’s declarations use Node types (Buffer, and imports from node:crypto, node:http and node:net), so install @types/node. TypeScript 6 no longer loads every @types package by default (types defaults to []), so on TypeScript 6+ also list it in tsconfig.json, or skipLibCheck: false reports Cannot find name 'Buffer' and Cannot find module 'node:http' inside the SDK’s declarations:

Installing from a local build

To try an unreleased commit, build and pack the SDK from a checkout of this repository, then install the tarball into your project - the same approach lousho init --sdk-path uses for the projects it generates. This is verified in CI by npm run pack-smoke, which installs the packed tarball into a fresh project and loads every entry point, in ESM and CJS:
To scaffold a new project the same way, from the checkout: node bin/lousho.js init ../my-agent --sdk-path .. On Windows, npx C:\abs\path\create-lousho-<version>.tgz silently does nothing (an npm quirk with absolute drive-letter paths). Use a relative path (npx ./create-lousho-<version>.tgz my-agent) or a file: spec (npx file:C:/abs/path/create-lousho-<version>.tgz my-agent) instead. npm install github:LinuxDevil/lousho does not work: dist/ is not in git and the repository has no prepare build step, so the install has no entry points.

Scaffolding a new project

lousho init creates a ready-to-run project: package.json (ESM, depending on this SDK by version range), a strict tsconfig.json, src/agent.ts calling createAgent({ model, instructions }) with an example defineTool() tool, an offline src/agent.test.ts using mockModel, a .env.example naming your provider’s key variable, .gitignore, a README, and an AGENTS.md (plus a one-line CLAUDE.md importing it) telling coding agents the project’s files, scripts and conventions. It then installs the dependencies and runs git init.
create-lousho (packages/create-lousho) is a thin wrapper that runs lousho init with the same arguments.

The lousho CLI

Installing the package also installs the lousho command: init, doctor, dev, chat, acp, add, mcp, eval, traces, build, studio, observe, bridge and more. See CLI for what each one does and its flags. Building needs tsup, an optional peer (see the table above): npm install --save-dev tsup.

Studio (optional)

The visual dashboard, Lousho Studio, is a separate package, lousho-studio - it is not part of this tarball. Install it with npm i -g lousho-studio (or run npx lousho-studio), or just run lousho studio inside a project that has the SDK: the launcher finds an installed Studio and opens the folder as a workspace. See Lousho Studio.

Troubleshooting: lousho doctor

Run npx lousho doctor right after installing. It prints one line per check with a status (ok, warn, FAIL), what it found, and, for anything that is not ok, the command to run or the setting to change:
What it checks:
  1. Your Node version against the package’s engines.node.
  2. The required peers ai and zod: installed, and within the SDK’s peerDependencies range (resolved from the current directory).
  3. The optional provider packages (@ai-sdk/openai, @ai-sdk/anthropic, and ollama-ai-provider on ai 4 or ollama-ai-provider-v2 on ai 6/7), with the npm install command for each missing one. A provider package that does not pair with the installed ai (for example ai 7 with @ai-sdk/openai 1.x) is flagged with the version to install instead.
  4. Whether each provider’s API key variable is set. Only the variable name and set / not set are printed, never the value. When OPENAI_BASE_URL or ANTHROPIC_BASE_URL is set (a local or OpenAI-compatible server), that provider’s line also shows the base URL, without any credentials or query string in it. It also shows which provider createAgent() would pick by default with your environment. OPENAI_BASE_URL is shown when set (without any credentials or query in it).
  5. With a spec path (lousho doctor agent.yaml): the spec is validated with field paths for every error, its provider package and key are checked (missing ones become failures), its tools must be built-in tools, and any mcpServers command must be resolvable. An agent directory or a .ts/.js agent module (lousho doctor src/agent.ts, what a scaffolded project’s npm run doctor runs) is loaded the way lousho dev loads it, and its model’s provider package and key are checked the same way. Without a path a missing key is only a warning, since doctor cannot know which provider your agent uses.
  6. Ollama reachability, only when the spec uses Ollama or OLLAMA_HOST is set.
  7. Docker availability, a warning only when the spec uses a sandboxed tool.
  8. With --ping: a GET for each provider whose variable is set, with a 5 s timeout, to an endpoint that needs the key: /models for OpenAI and Anthropic, /api/v1/key for OpenRouter (its /models answers without a key). A rejected key (HTTP 401/403) is a failure; an unreachable server is a warning. With OPENAI_BASE_URL set, <base>/models is pinged and the line says it shows reachability only, since a local server may not check keys. Keys are sent to their own provider only and never printed.
On Windows the fix lines use PowerShell syntax ($env:OPENAI_API_KEY="<your key>") instead of export. The exit code is 1 if any check fails and 0 otherwise (warnings do not fail), so it can gate CI. Add --json for machine-readable output. Colour is used only when stdout is a terminal and NO_COLOR is unset. For problems that are not about installing, see Troubleshooting. Coming from a 1.0.0-alpha.* release? See Upgrading to 1.0 for moved imports, removed and renamed APIs. Next: Quick Start.