aiki

A durable execution platform.

Durable execution is a fault-tolerant paradigm for building applications, especially long-running workflows. Some workflows take minutes, others take days, months or years. They wait on humans, survive crashes, retry on failure, and coordinate across systems. Building these with traditional code means wiring together message queues, crons, state machines, and fragile recovery logic.

With Aiki, workflows are plain TypeScript. The platform makes them durable: each workflow is a virtual thread of execution that can be suspended intentionally or due to crashes/intermittent failures, and automatically resumed from where it left off.

Aiki's architecture is a server that orchestrates, and workers or endpoints that execute — shipped as a library. Run everything in a single process, or pull the components apart as you grow. Where each component runs is configuration, not architecture; workflow code never changes.

Example: Subscription Trial

A workflow that activates a 14-day free trial and waits for the user to pay. If payment arrives early, it completes immediately. If the trial expires, the user is downgraded.

import { event, task, workflow } from "@aikirun/workflow";

const activateTrial = task({
  name: "activate-trial",
  async handler(userId: string) { /**/ },
});

const downgradeToFree = task({
  name: "downgrade-to-free",
  async handler(userId: string) { /**/ },
});

export const trialV1 = workflow({ name: "subscription-trial" }).v("1.0.0", {
  async handler(run, input: { userId: string }) {
    await activateTrial.start(run, input.userId);

    // Wait until payment is received or the 14-day trial expires
    const result = await run.events.paymentReceived.wait({ timeout: { days: 14 } });
    if (result.timeout) {
      await downgradeToFree.start(run, input.userId);
    }
  },
  events: {
    paymentReceived: event(),
  },
});

Behind this code, the workflow is persisted at every step: it survives crashes and waits out the 14 days without holding any system resources.

Quick Start

The Aiki server is a library: server({ db }) returns a fetch API HTTP handler (Request) => Promise<Response> and a background runtime. Mount the handler in any HTTP server — in the same process as your app, or in a process dedicated to Aiki. The example below runs everything in one process.

Install the SDK packages:

npm install @aikirun/workflow @aikirun/client @aikirun/worker @aikirun/server
npm install --save-dev @aikirun/cli

Apply Aiki's schema migration to your Postgres database:

DATABASE_URL=postgresql://user:password@localhost:5432/aiki \
  npx aiki migrate apply --package server

Save the trial workflow above to workflow.ts (exported as trialV1), then bootstrap and run it:

// app.ts
import { client } from "@aikirun/client";
import { database, server } from "@aikirun/server";
import { worker } from "@aikirun/worker";
import { trialV1 } from "./workflow";

const databaseUrl = process.env.DATABASE_URL ?? "postgresql://user:password@localhost:5432/aiki";

// Server and worker, both running in this process
const aikiServer = server({ db: database({ provider: "pg", url: databaseUrl }) });
const runtimeHandle = await aikiServer.runtime.start();

const aikiClient = client({ handler: aikiServer.handler });
const workerHandle = await worker({ workflows: [trialV1] }).spawn(aikiClient);

// Start the workflow
const handle = await trialV1.start(aikiClient, { userId: "user-123" });

// Simulate the payment arriving
await handle.events.paymentReceived.send();
await handle.waitForStatus("completed");

await workerHandle.stop();
await runtimeHandle.stop();

Run it:

npx tsx app.ts   # or: bun run app.ts

The trial activates, the payment event ends the 14-day wait early, and the run completes.

Above, the client invokes aikiServer.handler directly — no network hop. If the server runs in a different process, point the client at it with client({ url: "https://..." }). Workflow code is unchanged.

Bundled standalone server + dashboard

Prefer to run the server in its own process with a web dashboard? The repo ships a standalone server (app/server) and dashboard (app/dashboard) in a docker-compose.yml:

git clone https://github.com/aikirun/aiki.git && cd aiki

# Create a .env with your DATABASE_URL, then:
docker-compose up -d

# Server: http://localhost:9850 — Dashboard: http://localhost:9851

See the Installation Guide for env vars and configuration.

Features

Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                              Your Application                               │
│                    (Uses Aiki SDK to start workflows)                       │
└─────────────────────────────────────┬───────────────────────────────────────┘
                                      │
                                      ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                              Aiki Server                                    │
│             Orchestrates runs, persists state in your database              │
│         Embedded in your process, or hosted as a standalone service         │
└─────────────────────┬─────────────────────────────────┬─────────────────────┘
                      │                                 │
                      │ Pull (Subscribers)              │ Push (HTTP)
                      ▼                                 ▼
        ┌──────────────────────────┐       ┌──────────────────────────┐
        │  Workers                 │       │  Endpoints               │
        │  Long-lived processes    │       │  Serverless functions    │
        │  in your infrastructure  │       │  on any platform         │
        └──────────────────────────┘       └──────────────────────────┘

You choose where each component runs: everything in one process, a central server with distributed workers, or push-based execution on serverless functions. Workflow code stays the same.

Documentation

• Getting Started — Install, set up, and build your first workflow
• Core Concepts — Workflows, tasks, events, schedules, workers, and the client
• Guides — Determinism, retries, refactoring, reference IDs, and reliable hooks
• Architecture — How orchestration, state, and work discovery fit together
• Examples — Runnable workflows
• llms.txt — Docs index for AI agents and LLMs

Requirements

• Runtime: Node.js 18+ or Bun 1.0+
• Modules: ESM only (import/export); CommonJS is not supported
• Database: PostgreSQL 14+ (SQLite and MySQL coming soon)

See the Installation Guide for detailed setup instructions including environment variable configuration.

Packages

Core — what most projects install:

• @aikirun/workflow — Define workflows and tasks
• @aikirun/client — Typed connection to the Aiki server (embedded or hosted); workflows, workers, and schedules attach to it
• @aikirun/worker — Long-lived worker for pull-based execution
• @aikirun/server — Embeddable server library
• @aikirun/cli — aiki migrate and related tooling

Optional — add when you need it:

• @aikirun/endpoint — Run workflows on serverless platforms via push instead of pull
• @aikirun/iam — Multi-tenancy, API keys, and dashboard auth
• @aikirun/redis — Sub-second timer dispatch and cross-host work distribution

Community

Aiki is in alpha — APIs may change between releases. Feedback shapes where it goes:

• Discord — questions, feedback, and discussion
• GitHub Issues — bugs and feature requests

License

Apache 2.0 — see LICENSE