@assistant-ui/pinboard

Durable objects for Node: one live instance per id across a fleet, activated on the first request, serving its own Hono app. Part of harness-sdk. Mirrors the Python pinboard.

Install

pnpm add @assistant-ui/pinboard hono

Use

// hello.ts
import { pinned } from "@assistant-ui/pinboard";
import { Hono } from "hono";

export const Hello = pinned((ctx) => {
  let visits = 0;
  ctx.onStop(() => console.log(`evicted ${ctx.id}`));
  const app = new Hono();
  app.get("/", (c) =>
    c.json({ message: `Hello from ${ctx.id}`, visits: ++visits }),
  );
  return app;
});

// app.ts
import { serve } from "@assistant-ui/pinboard/node";
import { Hello } from "./hello.ts";

await serve({ hosts: { "/hello": Hello } });

• GET /hello/<id>/ reaches the instance for <id>; its app sees the path below /hello/<id>.
• c.env.pinned holds { ctx, attestation, epoch }; new Hono<Pinboard.Env>() types it.
• ctx.onStop, ctx.onAlarm, ctx.alarm, ctx.cluster, ctx.waitUntil: lifecycle, alarms, calls to other instances.
• PINBOARD_URL, PINBOARD_TOKEN, ADVERTISE_URL (read from the environment) register the worker with a gateway; without them it serves locally.
• worker.app mounts the worker into your own Hono app: app.route("/", worker.app).

Docs

• Reference: https://github.com/assistant-ui/harness-sdk/blob/main/apps/docs/app/pinboard/docs/reference/pinboard-js/page.mdx
• Spec: https://github.com/assistant-ui/harness-sdk/blob/main/apps/docs/app/pinboard/docs/spec/gateway-registry/page.mdx