Installation & SetupUsage GuideConfigurationAgents & ToolsMCP ServersSession SharingACP IntegrationSystem ArchitectureEmbedding GuideAPI ReferenceOverviewConfigurationCachingOverviewPaymentsIntegration GuideOpenClaw Plugin

Embedding Guide

Use otto as a library in your own applications.

Quick Start

The simplest way to embed otto is with createEmbeddedApp:

import { createEmbeddedApp } from "@ottocode/server";

const app = createEmbeddedApp({
  provider: "anthropic",
  model: "claude-sonnet-4",
  apiKey: process.env.ANTHROPIC_API_KEY,
  agent: "build",
});

Bun.serve({
  port: 9100,
  fetch: app.fetch,
  idleTimeout: 240,
});

Using the SDK Directly

import {
  generateText,
  resolveModel,
  discoverProjectTools,
} from "@ottocode/sdk";

const model = await resolveModel("anthropic", "claude-sonnet-4");
const tools = await discoverProjectTools(process.cwd());

const result = await generateText({
  model,
  prompt: "List all TypeScript files and count lines",
  tools: Object.fromEntries(
    tools.map((t) => [t.name, t.tool])
  ),
  maxSteps: 10,
});

Embedded App Options

OptionTypeDescription
providerstringAI provider name
modelstringModel identifier
apiKeystringProvider API key
agentstringAgent to use (build, plan, general, research)

Multi-Provider Auth

Pass multiple provider keys for provider switching:

const app = createEmbeddedApp({
  provider: "anthropic",
  model: "claude-sonnet-4",
  apiKey: process.env.ANTHROPIC_API_KEY,
  agent: "build",
  // Additional providers available for switching
  providers: {
    openai: { apiKey: process.env.OPENAI_API_KEY },
    google: { apiKey: process.env.GOOGLE_API_KEY },
  },
});

Custom Agents

Define custom agents when embedding:

const app = createEmbeddedApp({
  provider: "anthropic",
  model: "claude-sonnet-4",
  apiKey: process.env.ANTHROPIC_API_KEY,
  agent: "custom",
  agents: {
    custom: {
      tools: ["read", "write", "bash", "ripgrep"],
      prompt: "You are a specialized code reviewer...",
    },
  },
});

Serving the Web UI

The embedded app can also serve the built-in web UI:

import { createStandaloneApp } from "@ottocode/server";

// Includes web UI serving + API
const app = createStandaloneApp({
  provider: "anthropic",
  model: "claude-sonnet-4",
  apiKey: process.env.ANTHROPIC_API_KEY,
});

CORS Configuration

For cross-origin requests, configure CORS:

const app = createEmbeddedApp({
  // ... provider config
  cors: {
    origin: "http://localhost:3000",
    credentials: true,
  },
});

Packages

PackageUse Case
@ottocode/serverFull HTTP server with routes, SSE streaming, agent runtime
@ottocode/sdkCore SDK: tools, agents, auth, config, providers
@ottocode/apiType-safe API client for consuming otto server
@ottocode/web-sdkReact components and hooks for building UIs