@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. Coline hosts your logic; there are no servers to deploy unless you want them.

npx create-coline-app my-app

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
• coline.net.fetch — external HTTP through Coline's allowlist, with {{secret:KEY}} server-side credential injection

Test without a server

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);