Client and configuration

createViby() creates the long-lived server-side SDK client. Configure infrastructure once, then derive a tenant/user-scoped client for each authenticated operation.

createViby(config)

import { createViby } from "@viby/sdk";
import { openai } from "@ai-sdk/openai";

const viby = createViby({
  framework: "farmjs",
  model: openai("your-model-id"),
  storage: {
    // Omit database to use DATABASE_URL.
    artifacts,
    connections,
    secrets,
  },
  skills: {
    design: ["farming-labs/design-engineer"],
  },
});

The function validates mutually exclusive configuration, opens the selected storage and adapter boundaries, and returns Viby<Framework>. It does not run database migrations or contact the model. Configuration failures throw ConfigurationError before work begins.

VibyConfig

The deprecated top-level persistence, artifactStore, connectionStore, and secretStore aliases remain for compatibility. Do not configure an alias and its corresponding storage.* field at the same time.

Model or generation engine

Use model for the built-in bounded AI SDK agent. Use engine when the application supplies its own agent, orchestration runtime, or model protocol:

import { defineGenerationEngine } from "@viby/sdk/core";

const engine = defineGenerationEngine({
  id: "company-agent",
  provider: "internal",
  model: "frontend-v3",
  async generate(input, options) {
    return companyAgent.generate(input, options);
  },
});

const viby = createViby({ framework: "farmjs", engine });

Concrete provider and model identity are stored on each attempt. Model or engine objects and their credentials are never persisted.

Multiple models from one provider

Use modelsFrom() when one AI SDK provider instance should expose several models. default becomes the top-level model and the remaining keys become stable aliases accepted by generation requests:

import { createViby, modelsFrom } from "@viby/sdk";
import { createOpenAI } from "@ai-sdk/openai";

const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY });

const viby = createViby({
  framework: "farmjs",
  ...modelsFrom(openai, {
    default: "gpt-5.6-sol",
    terra: "gpt-5.6-terra",
    luna: "gpt-5.6-luna",
    fast: "gpt-5.6-sol-fast",
  }),
});

The provider instance still owns authentication, requests, streaming, tools, and usage reporting. Viby receives ordinary AI SDK LanguageModel objects and stores only their provider/model identity on durable attempts. Pass model: "terra" when creating or retrying a generation to select an alias.

The same helper accepts another provider instance without changing Viby configuration:

import { anthropic } from "@ai-sdk/anthropic";

const claudeModels = modelsFrom(anthropic, {
  default: "claude-sonnet-4-6",
  opus: "claude-opus-4-6",
});

Spreading claudeModels into createViby() makes Sonnet the default and exposes opus as a request alias. Viby invokes the returned AI SDK model objects internally; it does not call the provider instance through a separate private integration.

Viby

ScopedViby

const user = viby.forUser({ tenantId, userId });

Scoped clients are lightweight and do not own independent database connections. A resource outside the scope resolves to NotFoundError.

GenerationWorker

const worker = viby.worker({
  id: "generation-worker-eu-1",
  concurrency: 4,
  leaseMs: 30_000,
  heartbeatMs: 10_000,
  pollIntervalMs: 500,
});

Workers claim with leases and heartbeat while running. Lease tokens fence writes; a stale worker cannot append output after another worker safely reclaims an expired attempt.

Shutdown behavior

Call viby.close() once per root client. It stops embedded runs, previews, sandboxes, tool sources, integrations, environment stores, and persistence resources that Viby owns. The host remains responsible for shutting down its HTTP server, scheduler, telemetry exporter, and application-owned adapter clients.

Request-scoped durable generation workers can preserve sandbox-backed previews while still closing their local stores and provider clients:

await viby.close({ preserveSandboxes: true });

Use this only after the worker has handed its sandbox to a durable preview. The default remains false, so normal application shutdown still stops every locally tracked preview and sandbox.