Quick start

You do not need to compile Koko to get started. Install the TypeScript SDK, point it at a Koko binary (local path or team-provided runtime), and write automation scripts. Building from source is only for engine contributors — see Build from source.

What you need

• Node.js 18+
• A Koko runtime binary — from your team, a local build, or zig-out/bin/koko if you already have the repo checked out

1. Install the SDK

npm install koko-sdk

2. Launch and automate (recommended)

Browser.launch() spawns Koko, waits for CDP, and connects — one call, no manual serve step.

import { Browser } from "koko-sdk";

const launched = await Browser.launch({
  binary: "/path/to/koko", // required unless zig-out/bin/koko exists in repo root
});

const page = await launched.browser.newPage();
await page.goto("https://example.com", { waitUntil: "domcontentloaded" });
console.log(await page.title());

await launched.close();

If you cloned the Koko repo and already ran zig build, omit binary — the SDK defaults to zig-out/bin/koko relative to the repo.

3. Or connect to a running server

When Koko is already running (shared dev server, CI, or cloud runtime):

const browser = await Browser.connect("http://127.0.0.1:9222");
const page = await browser.newPage();
await page.goto("https://example.com");
await browser.close();

Start a server manually only if you need long-lived infrastructure — see Run CDP server.

4. Fetch a page from the terminal

No script required — useful for smoke tests and pipelines:

KOKO_CDP=http://127.0.0.1:9222 npx koko-fetch https://example.com

5. AI agents in Cursor

For MCP-based agent workflows, run the MCP server and connect from your IDE:

koko mcp --browser-profile chrome-macos-catalina

Details: Agents & MCP.

Choose your path