README.md
Open file@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 filescoline.storage.kv/coline.storage.collection(name)— app-private key-value state and queryable recordscoline.members,coline.notifications,coline.searchcoline.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);