First Project
This tutorial walks you through building a minimal Zakardo application from scratch. You will define a capability, configure the runtime, start the server, submit an intent, and inspect the trace.
What You Will Build
Section titled “What You Will Build”A simple note-taking service with two capabilities:
notes_list— list all notes (READ)notes_add— add a new note (WRITE_INTERNAL)
Step 1: Set Up the Project
Section titled “Step 1: Set Up the Project”mkdir my-notes-app && cd my-notes-apppnpm initpnpm add @zakardo/core hono @hono/node-server better-sqlite3 ajv ajv-formats semverpnpm add -D typescript @types/node @types/better-sqlite3 @types/semver tsxCreate a tsconfig.json:
{ "compilerOptions": { "target": "ES2022", "module": "NodeNext", "moduleResolution": "NodeNext", "strict": true, "esModuleInterop": true, "outDir": "dist", "rootDir": "src" }, "include": ["src"]}Add "type": "module" to your package.json.
Step 2: Define Capabilities
Section titled “Step 2: Define Capabilities”Create src/capabilities.ts:
import type { CapabilityDefinition, CapabilityFn } from '@zakardo/core';
// In-memory store for this tutorialconst notes: Array<{ id: string; title: string; body: string; created_at: string }> = [];
// --- List Notes ---
export const listNotesCapability: CapabilityDefinition = { name: 'notes_list', version: '1.0.0', description: 'List all notes, optionally filtered by title keyword.', effect_class: 'READ', boundary: 'LOCAL', input_schema: { type: 'object', properties: { keyword: { type: 'string', description: 'Filter notes by title keyword' }, }, 'x-zakardo': { kind: 'capability-input', version: '1.0.0' }, }, output_schema: { type: 'object', properties: { notes: { type: 'array', description: 'List of notes', items: { type: 'object', properties: { id: { type: 'string' }, title: { type: 'string' }, body: { type: 'string' }, }, }, }, count: { type: 'number', description: 'Total notes returned' }, }, 'x-zakardo': { kind: 'capability-output', version: '1.0.0' }, }, interaction_spec: null, anchored_view: null, tags: ['notes', 'read'], metadata: { author: 'tutorial', created_at: '2026-01-01T00:00:00Z', deprecated: false },} as CapabilityDefinition;
export const listNotesImpl: CapabilityFn = async (inputs) => { const keyword = inputs['keyword'] as string | undefined; let results = [...notes]; if (keyword) { results = results.filter((n) => n.title.toLowerCase().includes(keyword.toLowerCase())); } return { notes: results, count: results.length };};
// --- Add Note ---
export const addNoteCapability: CapabilityDefinition = { name: 'notes_add', version: '1.0.0', description: 'Add a new note with a title and body.', effect_class: 'WRITE_INTERNAL', boundary: 'LOCAL', input_schema: { type: 'object', required: ['title', 'body'], properties: { title: { type: 'string', description: 'Note title' }, body: { type: 'string', description: 'Note body content' }, }, 'x-zakardo': { kind: 'capability-input', version: '1.0.0' }, }, output_schema: { type: 'object', properties: { id: { type: 'string', description: 'Created note ID' }, title: { type: 'string', description: 'Note title' }, created: { type: 'boolean', description: 'Whether the note was created' }, }, 'x-zakardo': { kind: 'capability-output', version: '1.0.0' }, }, interaction_spec: null, anchored_view: null, tags: ['notes', 'write'], metadata: { author: 'tutorial', created_at: '2026-01-01T00:00:00Z', deprecated: false },} as CapabilityDefinition;
export const addNoteImpl: CapabilityFn = async (inputs) => { const id = `note_${crypto.randomUUID().slice(0, 8)}`; const note = { id, title: inputs['title'] as string, body: inputs['body'] as string, created_at: new Date().toISOString(), }; notes.push(note); return { id, title: note.title, created: true };};Each capability declares:
effect_class— what it does (READvsWRITE_INTERNAL)boundary— where it runs (LOCALmeans within the server process)input_schema/output_schema— typed JSON Schemas withx-zakardoextensionstags— for discovery and filtering
Step 3: Describe Your Application to the Planner
Section titled “Step 3: Describe Your Application to the Planner”Before starting the server, you need to tell the AI planner what your app does. This is the most important configuration in any Zakardo application. Without it, the planner has no context about your domain and will produce poor or unusable plans.
The application_prompt is injected into every planner LLM call as system context. It should describe:
- What your app does — the domain and purpose
- Who the users are — their roles and what they care about
- Key domain concepts — the entities and relationships
- Business rules — constraints the planner should respect
You can also add planning_hints — short, targeted rules for specific situations.
Step 4: Configure and Start the Server
Section titled “Step 4: Configure and Start the Server”Create src/server.ts:
import { Hono } from 'hono';import { serve } from '@hono/node-server';import { createZakardoApp, mountStudio, type ZakardoConfig } from '@zakardo/core';import { listNotesCapability, listNotesImpl, addNoteCapability, addNoteImpl,} from './capabilities.js';
const config: ZakardoConfig = { name: 'my-notes-app', version: '0.0.1', llm: { providers: [{ name: 'mock', type: 'mock' as const, models: ['mock-model'] }], default_model: 'mock-model', routing: {},
// Tell the planner what your app does (Layer 2) application_prompt: ` This is a personal note-taking application. Users create and search through text notes. Notes have a title and a body. Notes are never deleted, only archived. Keep responses concise and helpful. `,
// Domain-specific hints for the planner (Layer 4) planning_hints: [ 'When a user asks to "find" or "search" notes, use notes_list with a keyword filter.', 'When a user asks to "write" or "create" a note, use notes_add.', ], }, execution: { timeout_ms: 30_000, step_timeout_ms: 5_000 }, trace: { level: 'full' }, auth: { required: false },};
async function main() { const { app: zakardoApp, runtime } = await createZakardoApp({ config, capabilities: [listNotesCapability, addNoteCapability], implementations: [ { name: 'notes_list', version: '1.0.0', fn: listNotesImpl }, { name: 'notes_add', version: '1.0.0', fn: addNoteImpl }, ], policies: [], });
const app = new Hono(); app.route('/zakardo', zakardoApp); mountStudio(app, { basePath: '/studio' });
serve({ fetch: app.fetch, port: 3000 }); console.log('Notes app running at http://localhost:3000'); console.log('API: http://localhost:3000/zakardo/v1/health'); console.log('Studio: http://localhost:3000/studio');}
main().catch(console.error);Start the server:
npx tsx src/server.tsStep 5: Verify It Works
Section titled “Step 5: Verify It Works”Check the health endpoint:
curl http://localhost:3000/zakardo/v1/healthList registered capabilities:
curl http://localhost:3000/zakardo/v1/capabilitiesYou should see both notes_list and notes_add in the response.
Step 6: Submit an Intent
Section titled “Step 6: Submit an Intent”Use the client SDK or curl to submit an intent:
curl -X POST http://localhost:3000/zakardo/v1/intent \ -H "Content-Type: application/json" \ -d '{"intent": {"expressed": "Show me all my notes"}}'The planner will classify the intent, generate a plan using notes_list, and return the result.
Step 7: Use the Client SDK
Section titled “Step 7: Use the Client SDK”For a typed experience, use @zakardo/client:
pnpm add @zakardo/clientimport { ZakardoClient } from '@zakardo/client';
const client = new ZakardoClient({ baseUrl: 'http://localhost:3000/zakardo/v1',});
// Submit an intentconst result = await client.intent.submit({ intent: { expressed: 'Add a note titled Meeting Notes with body Discuss Q1 roadmap' },});console.log('Response mode:', result.mode);
// List capabilitiesconst caps = await client.capabilities.list();console.log( 'Capabilities:', caps.map((c) => c.name),);Step 8: Explore with Studio
Section titled “Step 8: Explore with Studio”Open http://localhost:3000/studio in your browser to access Zakardo Studio:
- Capability Browser — see your registered capabilities with their schemas
- Intent Playground — submit intents and watch the planner pipeline
- Trace Viewer — inspect execution traces step by step
Next Steps
Section titled “Next Steps”- Configure the Planner — write effective application prompts and planning hints
- Understand Capabilities in depth — effect classes, boundaries, interaction specs
- Build a full CRM with 10 capabilities and governance policies
- Write governance policies to add approval gates for destructive operations
- Explore the API Reference for detailed type documentation