Self-Hosted Inngest on macOS

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.

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

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:

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

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

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

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

Step 2: Create the Inngest client

// 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

// 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

// 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

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:

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:

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

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

Cron Functions

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

Claim-Check Pattern

Large data between steps: write to file, pass path.

// ❌ DON'T: return large data from a step
const transcript = await step.run("transcribe", async () => {
  return { text: hugeString }; // Step output has size limits!
});

// ✅ DO: write to file, return path
const transcriptPath = await step.run("transcribe", async () => {
  const result = await transcribe(audioPath);
  await Bun.write("/​tmp/​transcript.json", JSON.stringify(result));
  return "/​tmp/​transcript.json";
});

Make It Survive Reboots

Worker via launchd

<!-- ~/​Library/​LaunchAgents/​com.you.inngest-worker.plist -->
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/​DTDs/​PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</​key><string>com.you.inngest-worker</​string>
  <key>ProgramArguments</​key>
  <array>
    <string>/​Users/​you/​.bun/​bin/​bun</​string>
    <string>run</​string>
    <string>/​path/​to/​your/​worker/​src/​serve.ts</​string>
  </​array>
  <key>EnvironmentVariables</​key>
  <dict>
    <key>INNGEST_DEV</​key><string>1</​string>
    <key>HOME</​key><string>/​Users/​you</​string>
    <key>PATH</​key><string>/​usr/​local/​bin:/​usr/​bin:/​bin:/​Users/​you/​.bun/​bin</​string>
  </​dict>
  <key>RunAtLoad</​key><true/>
  <key>KeepAlive</​key><true/>
  <key>StandardOutPath</​key><string>/​tmp/​inngest-worker.log</​string>
  <key>StandardErrorPath</​key><string>/​tmp/​inngest-worker.log</​string>
  <key>WorkingDirectory</​key><string>/​path/​to/​your/​worker</​string>
</​dict>
</​plist>

Load:

launchctl load ~/​Library/​LaunchAgents/​com.you.inngest-worker.plist

What happens on reboot

1. Docker starts → Inngest server comes up with persisted state (SQLite)
2. launchd starts → worker process registers functions
3. Any incomplete function runs resume from their last completed step

Gotchas

1. @inngest/​ai is a required peer dep. bun add inngest alone isn't enough — the SDK imports @inngest/​ai at startup. Worker crashes with Cannot find module '@inngest/​ai'. Always install both.

2. Docker-to-host networking. If Inngest runs in Docker and the worker on the host, the server can't reach localhost:3111. Pass --sdk-url http://host.docker.internal:3111/​api/​inngest on the docker run command. This is Docker Desktop/​OrbStack-specific; Linux Docker needs --add-host=host.docker.internal:host-gateway.

3. Service naming in k8s: Never name a Service the same as the binary. INNGEST_PORT env var collision crashes the container.

4. Step output size: Keep step return values small. Use claim-check pattern for large data.

5. Worker re-registration: After Inngest server restart, the worker needs to re-register. Restart the worker or hit the registration endpoint.

6. Trigger drift: Functions register their triggers at startup. If you change a trigger in code but the server has stale state, the old trigger stays active. Build an auditor or restart both server and worker.

7. INNGEST_DEV=1: Required for local development. Without it, the worker tries to register with Inngest Cloud.

8. Concurrency = 1 for GPU work: Transcription, inference — anything that saturates a GPU needs concurrency: { limit: 1 }.

Verification

• Inngest dashboard accessible at http://localhost:8288
• Worker shows as registered in dashboard (Functions tab)
• Send a test event — function executes in dashboard
• Kill the worker mid-function — restart worker, function resumes from last step
• (Tier 2+) Restart Docker — Inngest state is preserved
• (launchd) Reboot Mac — worker and Inngest both come back automatically

Setup Script (curl-first)

For automated setup, the user can run:

curl -sL joelclaw.com/​scripts/​inngest-setup.sh | bash

Or with a specific tier:

curl -sL joelclaw.com/​scripts/​inngest-setup.sh | bash -s -- 2

The script is idempotent, detects existing state, and scaffolds a worker with typed events.

Decision Chain (compressed ADRs)

This skill's architecture is backed by a chain of Architecture Decision Records. Unfurl as needed for tradeoff context.

ADR-0010 → ADR-0029 → current state

Credits

• Inngest — the workflow engine
• joelclaw.com/​inngest-is-the-nervous-system — architecture narrative
• joelclaw.com/​self-hosting-inngest-background-tasks — human summary