Skip to content

Installation

  • Node.js 20 or later
  • pnpm 9 or later (recommended) or npm/yarn
  • TypeScript 5.x (strict mode)

The fastest way to get started is with the scaffolding CLI:

Terminal window
npx create-zakardo my-app

This 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 /studio in development
  • TypeScript strict mode, ESM, and Vitest pre-configured

To add Zakardo to an existing project, install the packages you need:

Terminal window
pnpm add @zakardo/core

This 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.

@zakardo/core requires the following peer dependencies:

Terminal window
# HTTP server
pnpm add hono @hono/node-server
# Runtime storage
pnpm add better-sqlite3
pnpm add -D @types/better-sqlite3
# Schema validation (used internally)
pnpm add ajv ajv-formats
# Semver operations (used internally)
pnpm add semver
pnpm add -D @types/semver

LLM 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:

Terminal window
# OpenAI
pnpm add openai
# Anthropic
pnpm add @anthropic-ai/sdk
# Google Gemini
pnpm add @google/generative-ai
# Ollama (local models)
pnpm add ollama

For frontend applications or external services consuming the API:

Terminal window
pnpm add @zakardo/client

Zero runtime dependencies — uses platform fetch and ReadableStream.

For testing capabilities, plans, and training datasets:

Terminal window
pnpm add -D @zakardo/testing

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.json

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:

Terminal window
curl http://localhost:3000/zakardo/v1/health
# Should return: { "status": "ok", ... }