First steps

In this guide, you'll create your first Keel application and run it in Keel Studio, a local workspace for interacting with your agents and inspecting their turns. Along the way, you'll see how State, Model, and Context come together in a turn.

Prerequisites

You'll need Node.js 20 or later and a package manager: npm, pnpm, Yarn, or Bun. The generated application uses TypeScript, so some familiarity with it will help you follow the examples.

You don't need an API key to get started. The starter includes a scripted model that returns predefined responses, letting you explore the application and Studio before connecting a provider.

Create a project

Use the Keel CLI to create your application:

npx @keel-dev/cli@next new my-assistant

pnpm dlx @keel-dev/cli@next new my-assistant

yarn dlx @keel-dev/cli@next new my-assistant

bunx @keel-dev/cli@next new my-assistant

This preview release uses the next npm tag.

Project names must start with a lowercase letter and use only lowercase letters, digits, and hyphens — my-assistant works; MyAssistant is refused at the door.

The CLI asks which package manager you'd like to use, creates a my-assistant directory, and installs its dependencies. The starter includes one assistant, a deterministic model, a unit test, and the configuration needed to run in Studio. For automation, pass --package-manager npm; noninteractive runs default to npm. Use --skip-install to create files without installing. Existing directories are never overwritten.

Move into your project:

cd my-assistant

Explore the project

The starter keeps the assistant's definitions together and the application's shared state in its own directory:

src/
├── main.ts
├── ambient.ts
├── app.ts
├── budgets.ts
├── shared/
│   └── state/
│       └── profile.block.ts
└── agents/
    └── assistant/
        ├── assistant.agent.ts
        ├── assistant.prompt.ts
        ├── assistant.chain.ts
        ├── assistant.mock.ts
        └── index.ts

Here's where the three pillars appear:

The assistant.agent.ts file brings the assistant's definitions together. ambient.ts declares the scope — the typed facts your product knows about a turn, validated at the admit gate. Execution limits live in budgets.ts; every ceiling is declared there or boot refuses. app.ts is the composition root that wires the assistant to the runtime and exposes the app to Studio, and main.ts runs one turn from the terminal.

Starter files import each other through the @app/* alias, which maps to src/* (declared in tsconfig.json paths — Studio and keel dev resolve it too), so there are no ../../.. chains to maintain.

You can explore these files as you go. For now, the starter is ready to run.

Run your application

Start the development server:

npm run dev

pnpm dev

yarn dev

bun run dev

Open Keel Studio at localhost:4180. Your application is loaded and ready for its first message.

Studio gives you a place to try your assistant and inspect what happened during each turn. You'll use it throughout these guides as you add state, connect models, and build out your application.

Test and build

npm test
npm run check-types
npm run build
npm start -- Hello

The build compiles your TypeScript app to dist/. npm start runs a turn from the terminal. npm run studio:build separately builds a static Studio for local inspection; it does not create a production API server.

Run your first turn

Send Hello in Studio. The starter's scripted model returns a predefined greeting, completing your first turn.

Select the turn to explore it:

• TURNS shows the turn crossing its gates, live, with its final outcome.
• TURN RECORDS shows the settled record — the budget granted, steps used, and how the turn ended.
• CONTEXT shows the instructions and information supplied to the model.
• MODEL shows the model's execution, including any tool calls.
• STATE shows what information was read or updated.
• WIRE shows the response sent back to the client.

This is the mental model you'll build on: each message starts a unit of work whose inputs, execution, and result you can inspect.

For a fuller tour of the panels and timeline, see Keel Studio.

Make your first change

Open src/agents/assistant/assistant.mock.ts and change the scripted greeting. Save the file, then send Hello again in a new Studio thread to see your updated response.

The scripted model helps you try a known behavior. It doesn't generate new answers from your instructions. When you're ready for that, follow the Model guide to connect a provider, then edit assistant.prompt.ts to shape how your assistant responds. You can inspect the resulting instructions in Studio's CONTEXT panel.

Next: State — define what your application remembers across turns.