@colineapp/sdk

The Coline App SDK — define apps that live inside Coline workspaces: Kairo tools, file types with rich previews, home surfaces, app storage, scheduled triggers, and external API access — and public websites with Coline Sites. Coline hosts your logic; there are no servers to deploy unless you want them.

npx create-coline-app my-app                    # an app for a workspace
npx create-coline-app my-site --template site   # a public website, no account needed

Docs: docs.coline.app · for coding agents: docs.coline.app/agents.md

Define an app

import { z } from "zod/v4";
import { defineApp, defineTool, ui } from "@colineapp/sdk/v2";

const createTodo = defineTool({
  name: "todos.create_todo",
  description: "Create a todo with a title.",
  input: z.object({ title: z.string().min(1) }),
  effect: "write", // enforced by the runtime as a hard capability ceiling
  execute: async (input, ctx) => {
    const file = await ctx.coline.files.create({
      typeKey: "todos.todo",
      name: input.title,
      document: { title: input.title, status: "open" },
    });
    return {
      output: { fileId: file.fileId },
      card: ui.reference({ kind: "file", id: file.fileId }),
    };
  },
});

export default defineApp({
  key: "todos",
  name: "Todos",
  permissions: ["files.read", "files.write", "ai.tools"],
  hosting: { default: "coline" },
  surfaces: { home: { tier: "tree" } },
  tools: [createTodo],
  handlers: {
    renderHome: async (ctx) => {
      const { files } = await ctx.coline.files.list({ typeKey: "todos.todo" });
      return ui.stack([
        ui.heading("Todos"),
        ...files.map((f) => ui.fileCard({ title: f.name, fileId: f.fileId })),
      ]);
    },
  },
});

One definition produces two artifacts: a serializable manifest (what the app may do — reviewed and consented to) and a runtime bundle (what it does). Every capability call is checked against the workspace's grants, the acting user's access, and the declared tool effect.

The capability API

The same coline.* object everywhere your code runs — tools, render handlers, schedules, hosted or external:

coline.files — create/read/update/trash workspace files
coline.storage.kv / coline.storage.collection(name) — app-private key-value state and queryable records
coline.members, coline.notifications, coline.search

import { createTestWorkspace } from "@colineapp/sdk/testing";
import app from "./app.config";

const ws = createTestWorkspace(app);
await ws.invokeTool("todos.create_todo", { title: "Ship it" });
expect(ws.files.byType("todos.todo")).toHaveLength(1);

Entry	Contents
`@colineapp/sdk/v2`	`defineApp`, `defineTool`, `defineFileType`, `ui`, `actions`, manifest schemas, capability types, `createColineAppHandler` for external hosting
`@colineapp/sdk/testing`	`createTestWorkspace` — the in-memory test harness
`@colineapp/sdk`	The legacy v1 surface (frozen; do not use for new apps)

import { watchAiJob } from "@colineapp/sdk/v2";

const model = (await coline.ai.models()).find((entry) => entry.kind === "language");
if (!model) throw new Error("No language model is configured");
const job = await coline.ai.run({
  kind: "language",
  input: {
    model: model.id,
    prompt: "Write a short welcome message",
    idempotencyKey: crypto.randomUUID(),
    maxCostMicrousd: model.priceMicrousd,
  },
});
for await (const update of watchAiJob(coline.ai, job.id)) {
  if (update.type === "event") console.log(update.event);
  else console.log(update.job.status, update.job.output);
}

colinesdk

colinesdk

@colineapp/sdk

Define an app

The capability API

Test without a server

Exports

Docs

Workflow

Live collections and access

Coline AI jobs

Full-stack apps

Coline Sites