Skip to content

Getting started

This page takes you from a clean checkout to a running agent. It should take a couple of minutes.

Prerequisites

  • Node.js 22 or newer. Check with node -v. The repo pins a version in .nvmrc, so nvm use picks it up if you use nvm.
  • An API key for a model, or a local Ollama install. The starter agent uses OpenRouter, which has a free tier and needs only a key, no local setup. If you'd rather run fully offline, see Running offline.

Install and build

From the repo root:

npm install
npm run build

npm install sets up every workspace. npm run build compiles the packages and builds the canvas UI. You need the build step before kampong dev can serve the canvas, because it serves the compiled assets rather than a live dev server.

Working on the tool itself?

npm test runs the fast unit and integration layers. See AGENTS.md in the repo for the full command list and contributor conventions.

The kampong command

The examples call kampong. After the build, npm link -w packages/cli puts it on your PATH. Without linking, run node packages/cli/dist/cli.js in its place.

Set your API key

Secrets never live in a spec file. A spec only ever references an environment variable, like ${OPENROUTER_API_KEY}. The real value lives in your environment or a .env file.

cp .env.example .env

Open .env and set your key:

OPENROUTER_API_KEY=sk-or-...

Get a free key at openrouter.ai/keys.

Run the starter agent

The repo ships a starter spec at examples/agent.yaml. Point a headless run at it:

kampong run examples/agent.yaml --input "Hi, what can you do?"

You'll see the run's steps stream by, then the final output. That's a complete agent executing against a real model call.

Open the canvas

To see and edit the same agent visually:

kampong dev examples

kampong dev starts a local server and prints a URL, by default http://localhost:4310. Open it. You'll see the agent laid out as blocks, the trigger and the workflow step, with a </> button in the top bar (or Alt+Y) that opens a read-only YAML drawer for developers. Edit the file in any editor and the canvas updates. Press Run, type an input, and watch the trace fill in step by step.

Running the app in Docker

If you juggle several projects and ports collide, make up runs the canvas in a container on one configurable port (HOST_PORT in .env, default 4310). make up seeds workspace/agent.yaml from the starter spec on first run, make logs follows the logs, and make down stops it.

Running it as a shared, signed-in service

kampong dev is single-user and edits one file. There is also a hosted app, the same canvas with sign-in, per-workspace specs, and server-side provider keys, for running Kampong Agents as a multi-tenant service. The agent-building steps in this tutorial are identical in both.

What just happened

You ran one AgentSpec file two ways, headless and on the canvas, with no import or conversion between them. That file is the unit you'll build up from here.

Next: Your first agent, which pulls the starter spec apart field by field and starts extending it.