The host bridge

Start from a fresh project

This guide is self-contained. Create an empty Ayjnt project, then replace the starter agent with the files shown below. Run commands from the new project directory unless a step says otherwise.

bunx ayjnt new try-host-bridge --empty
cd try-host-bridge
bun install

# remove agents/alive once you are ready to add the guide's files

A boundary, not a shared global

Agent code runs in workerd. Host tools run in Bun. Ayjnt sends a tool description and validated input across a private bridge; the Bun implementation never ships into the isolate.

The bridge is active under ayjnt run and compiled executables. Deployed Cloudflare Workers have no Bun host process, so host tools are rejected unless explicitly marked optional on deploy.

Declare side effects

import { z } from "zod";
import { confinePath, hostTool } from "ayjnt/tools";

const root = process.cwd();

export const readProjectFile = hostTool({
  description: "Read a UTF-8 file inside the project.",
  sideEffects: "read",
  inputSchema: z.object({ path: z.string() }),
  execute: ({ path }) => Bun.file(confinePath(root, path)).text(),
});

Run it and verify the result

Run with the documented host permission flag, invoke the host tool, and confirm the agent receives only its serialized result.

bun run build
bun run dev

# the local app is now available at http://localhost:8787