inngest-local

What this skill does

# Self-Hosted Inngest on macOS

This skill sets up Inngest as a self-hosted durable workflow engine on a Mac. Inngest gives you event-driven functions where each step retries independently — if step 3 of 5 fails, only step 3 retries.

## Before You Start

**Required:**
- macOS with Docker (Docker Desktop, OrbStack, or Colima)
- Bun or Node.js for the worker process

**Optional:**
- k8s cluster (Talos on Colima, etc.) for persistent deployment
- Redis (for state sharing between functions and gateway integration)

## Intent Alignment

Ask the user these questions to determine scope.

### Question 1: What are you building?

1. **Quick experiment** — I want to try Inngest, run a function, see the dashboard
2. **Persistent setup** — I want this running all the time, surviving reboots, with real workflows
3. **Full infrastructure** — I want k8s-deployed Inngest with persistent storage, integrated with an agent gateway

### Question 2: What runtime for the worker?

1. **Bun** — fast, good TypeScript support, what joelclaw uses
2. **Node.js** — standard, widest compatibility
3. **Existing framework** — I have a Next.js/Express/Hono app already

### Question 3: What kind of work?

1. **AI agent tasks** — coding loops, content processing, transcription pipelines
2. **General background jobs** — scheduled tasks, webhooks, data processing
3. **Both** — mixed workloads

## Setup Tiers

### Signing Keys (required)

As of Feb 2026, `inngest/inngest:latest` requires signing keys. Without them the container crash-loops with `Error: signing-key is required`.

```bash
# Generate once, reuse across tiers
INNGEST_SIGNING_KEY="signkey-dev-$(openssl rand -hex 16)"
INNGEST_EVENT_KEY="evtkey-dev-$(openssl rand -hex 16)"
echo "INNGEST_SIGNING_KEY=$INNGEST_SIGNING_KEY" >> .env.inngest
echo "INNGEST_EVENT_KEY=$INNGEST_EVENT_KEY" >> .env.inngest
```

### Tier 1: Docker One-Liner (experiment)

Get Inngest running in 30 seconds:

```bash
docker run -d --name inngest \
  -p 8288:8288 \
  -e INNGEST_SIGNING_KEY="$INNGEST_SIGNING_KEY" \
  -e INNGEST_EVENT_KEY="$INNGEST_EVENT_KEY" \
  inngest/inngest:latest \
  inngest start --host 0.0.0.0
```

Open http://localhost:8288 — you should see the Inngest dashboard.

**Limitation:** No persistent state. Container restart = lost history. Fine for experimenting.

### Tier 2: Persistent Docker (daily driver)

Add a volume for SQLite state:

```bash
docker run -d --name inngest \
  -p 8288:8288 \
  -v inngest-data:/var/lib/inngest \
  -e INNGEST_SIGNING_KEY="$INNGEST_SIGNING_KEY" \
  -e INNGEST_EVENT_KEY="$INNGEST_EVENT_KEY" \
  --restart unless-stopped \
  inngest/inngest:latest \
  inngest start --host 0.0.0.0
```

Now Inngest state survives container restarts. `--restart unless-stopped` brings it back after Docker restarts.

### Tier 3: Kubernetes (production-grade)

For full persistence with proper health checks. Requires a k8s cluster (Talos on Colima, etc.).

```yaml
# inngest.yaml
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: inngest
  namespace: default
spec:
  serviceName: inngest-svc  # NOT "inngest" — avoids env var collision
  replicas: 1
  selector:
    matchLabels:
      app: inngest
  template:
    metadata:
      labels:
        app: inngest
    spec:
      containers:
      - name: inngest
        image: inngest/inngest:latest
        command: ["inngest", "start", "--host", "0.0.0.0"]
        ports:
        - containerPort: 8288
        volumeMounts:
        - name: data
          mountPath: /var/lib/inngest
  volumeClaimTemplates:
  - metadata:
      name: data
    spec:
      accessModes: ["ReadWriteOnce"]
      resources:
        requests:
          storage: 5Gi
---
apiVersion: v1
kind: Service
metadata:
  name: inngest-svc  # CRITICAL: not "inngest" — k8s creates INNGEST_PORT env var that conflicts
  namespace: default
spec:
  type: NodePort
  selector:
    app: inngest
  ports:
  - port: 8288
    targetPort: 8288
    nodePort: 8288
```

Apply:
```bash
kubectl apply -f inngest.yaml
```

**⚠️ GOTCHA:** Never name a k8s Service the same as the binary it runs. A Service named `inngest` creates `INNGEST_PORT=tcp://10.43.x.x:8288`. The Inngest binary expects `INNGEST_PORT` to be an integer. Name it `inngest-svc`.

## Build a Worker

### Step 1: Initialize

```bash
mkdir my-worker && cd my-worker
bun init -y
bun add inngest @inngest/ai hono
```

### Step 2: Create the Inngest client

```typescript
// src/inngest.ts
import { Inngest } from "inngest";

// Type your events for full type safety
type Events = {
  "task/process": { data: { url: string; outputPath: string } };
  "task/completed": { data: { url: string; result: string } };
};

export const inngest = new Inngest({
  id: "my-worker",
  schemas: new EventSchemas().fromRecord<Events>(),
});
```

### Step 3: Write your first function

```typescript
// src/functions/process-task.ts
import { inngest } from "../inngest";

export const processTask = inngest.createFunction(
  {
    id: "process-task",
    concurrency: { limit: 1 },  // one at a time
    retries: 3,
  },
  { event: "task/process" },
  async ({ event, step }) => {
    // Step 1: Download — retries independently on failure
    const localPath = await step.run("download", async () => {
      const response = await fetch(event.data.url);
      const buffer = await response.arrayBuffer();
      const path = `/tmp/downloads/${crypto.randomUUID()}.bin`;
      await Bun.write(path, buffer);
      return path;  // Only the path is stored in step state (claim-check pattern)
    });

    // Step 2: Process — if this fails, download doesn't re-run
    const result = await step.run("process", async () => {
      const data = await Bun.file(localPath).text();
      // ... your processing logic
      return { processed: true, size: data.length };
    });

    // Step 3: Emit completion event — chains to other functions
    await step.sendEvent("notify-complete", {
      name: "task/completed",
      data: { url: event.data.url, result: JSON.stringify(result) },
    });

    return { status: "done", result };
  }
);
```

### Step 4: Serve it

```typescript
// src/serve.ts
import { Hono } from "hono";
import { serve as inngestServe } from "inngest/hono";
import { inngest } from "./inngest";
import { processTask } from "./functions/process-task";

const app = new Hono();

// Health check
app.get("/", (c) => c.json({ status: "running", functions: 1 }));

// Inngest endpoint — registers functions with the server
app.on(
  ["GET", "POST", "PUT"],
  "/api/inngest",
  inngestServe({ client: inngest, functions: [processTask] })
);

export default {
  port: 3111,
  fetch: app.fetch,
};
```

### Step 5: Run it

```bash
INNGEST_DEV=1 bun run src/serve.ts
```

The worker starts, registers with Inngest at localhost:8288, and your function appears in the dashboard.

### Step 6: Test it

Send an event via the dashboard (Events → Send Event) or curl:

```bash
curl -X POST http://localhost:8288/e/key \
  -H "Content-Type: application/json" \
  -d '{"name": "task/process", "data": {"url": "https://example.com/file.txt", "outputPath": "/tmp/out"}}'
```

Watch it execute step-by-step in the dashboard.

## Patterns

### Event Chaining

Function A emits an event that triggers Function B:

```typescript
// In function A:
await step.sendEvent("chain", { name: "pipeline/step-two", data: { result } });

// Function B triggers on that event:
export const stepTwo = inngest.createFunction(
  { id: "step-two" },
  { event: "pipeline/step-two" },
  async ({ event, step }) => { /* ... */ }
);
```

### Concurrency Keys

Run one instance per project, but allow parallel across projects:

```typescript
concurrency: {
  key: "event.data.project",
  limit: 1,
}
```

### Cron Functions

```typescript
export const heartbeat = inngest.createFunction(
  { id: "heartbeat" },
  [{ cron: "*/15 * * * *" }],
  async ({ step }) => {
    await step.run("check-health", async () => {
      // ... system health checks
    });
  }
);
```

### Claim-Check Pattern

Large