Installation
Prerequisites
Section titled “Prerequisites”- Node.js 20 or later
- pnpm 9 or later (recommended) or npm/yarn
- TypeScript 5.x (strict mode)
Create a New Project
Section titled “Create a New Project”The fastest way to get started is with the scaffolding CLI:
npx create-zakardo my-appThis generates a monorepo with:
- A Hono backend with Zakardo Runtime pre-configured
- Example capabilities and governance policies
- A React frontend with A2UI surfaces
- Zakardo Studio mounted at
/studioin development - TypeScript strict mode, ESM, and Vitest pre-configured
Manual Installation
Section titled “Manual Installation”To add Zakardo to an existing project, install the packages you need:
Core Runtime (required)
Section titled “Core Runtime (required)”pnpm add @zakardo/coreThis includes the type system, capability registry, Plan IR, enrichment pipeline, validator, execution engine, policy engine, trace system, planner, plan library, training system, config, and Hono server.
Peer Dependencies
Section titled “Peer Dependencies”@zakardo/core requires the following peer dependencies:
# HTTP serverpnpm add hono @hono/node-server
# Runtime storagepnpm add better-sqlite3pnpm add -D @types/better-sqlite3
# Schema validation (used internally)pnpm add ajv ajv-formats
# Semver operations (used internally)pnpm add semverpnpm add -D @types/semverLLM Providers (at least one required for planning)
Section titled “LLM Providers (at least one required for planning)”Install the SDK for your preferred LLM provider:
# OpenAIpnpm add openai
# Anthropicpnpm add @anthropic-ai/sdk
# Google Geminipnpm add @google/generative-ai
# Ollama (local models)pnpm add ollamaClient SDK (optional)
Section titled “Client SDK (optional)”For frontend applications or external services consuming the API:
pnpm add @zakardo/clientZero runtime dependencies — uses platform fetch and ReadableStream.
Testing Utilities (optional)
Section titled “Testing Utilities (optional)”For testing capabilities, plans, and training datasets:
pnpm add -D @zakardo/testingProject Structure
Section titled “Project Structure”A typical Zakardo application follows this monorepo structure:
my-app/├── apps/│ ├── api/ # Hono backend│ │ ├── src/│ │ │ ├── server.ts # Hono + Zakardo Runtime setup│ │ │ ├── capabilities/ # Capability definitions + implementations│ │ │ └── policies/ # Governance policies│ │ └── package.json│ └── web/ # React frontend├── packages/│ ├── db/ # Database schema (Prisma/Drizzle)│ └── shared/ # Shared types and constants├── training/ # Training datasets├── pnpm-workspace.yaml├── turbo.json└── tsconfig.jsonVerify Installation
Section titled “Verify Installation”Create a minimal server.ts to verify everything works:
import { Hono } from 'hono';import { serve } from '@hono/node-server';import { createZakardoApp, type ZakardoConfig } from '@zakardo/core';
const config: ZakardoConfig = { name: 'test', version: '0.0.1', llm: { providers: [{ name: 'mock', type: 'mock' as const, models: ['mock-model'] }], default_model: 'mock-model', routing: {}, }, execution: { timeout_ms: 30_000, step_timeout_ms: 5_000 }, trace: { level: 'full' }, auth: { required: false },};
const { app: zakardoApp } = await createZakardoApp({ config, capabilities: [], implementations: [], policies: [],});
const app = new Hono();app.route('/zakardo', zakardoApp);
serve({ fetch: app.fetch, port: 3000 });console.log('Zakardo running at http://localhost:3000/zakardo/v1');Then hit the health endpoint:
curl http://localhost:3000/zakardo/v1/health# Should return: { "status": "ok", ... }Next Steps
Section titled “Next Steps”- Build your first project with a complete tutorial
- Understand capabilities before writing your own