hark · docs

Start talking

Sign in with Cloudflare and pick the account hark should think with.
Turn on authentication for an AI Gateway in that account. hark uses default unless told otherwise, and tells you where the toggle is if it is missing.
Tap the ear, or press space. Allow the microphone once.
Talk. Interrupt it when you like. Say “thanks, that is all” to put it to sleep.

What to ask

Say	You get
“What is the weather in Lisbon?”	A forecast card and a spoken answer.
“Who was Ada Lovelace?”	An article card and a short answer.
“Set a timer for ten minutes.”	A live countdown. hark speaks when it ends.
“Remember that I take my coffee black.”	A saved memory. “Forget that” removes it.
“What am I holding?” (camera on)	One frame, described by a vision model.
“Paint me a lighthouse in a storm.”	A FLUX picture on screen.
“Build me a 3D rocket.”	The embers sculpt it and spin it.
“Scaffold a node project and run it.”	A terminal card from your own durable Linux box.
“Give me a status report on my account.”	A report card. With biometrics on, changes need your passkey (how).
“Connect my server” and a URL	Your MCP server’s tools, by voice.

How a turn works

mic → 16 kHz PCM, 80 ms frames → WebSocket → your Durable Object
      → Deepgram Flux (through your AI Gateway)
        EagerEndOfTurn → start thinking, hold audio behind a gate
        TurnResumed    → throw that work away
        EndOfTurn      → same words? open the gate : start over
      → Workers AI brain, streamed, with tools
      → sentence chunker → Aura, three in flight
      → 24 kHz PCM tagged with its turn → your speaker

When you talk over it, hark ducks its volume at once. If what you said is words, the turn is interrupted, the model request is aborted, and the browser drops queued audio for that turn. Speaking ends only when the browser reports its buffer is empty.

Your account, your token

Sign-in asks for offline_access ai.read ai.write and gateway access. That is all hark needs.
Your grant lives in a Durable Object. Your browser gets only a signed session cookie. The token is never sent to the page.
Every model call goes through your own authenticated AI Gateway, so you see every request and its cost there.
Revoke access at any time in your Cloudflare profile. Signing out revokes it too.

Connect your MCP servers

hark is an MCP client. Connect a server and its tools are available by voice.

Say “connect my server” with a name and an https URL, or add it in Settings, Your MCP servers.
If the server uses OAuth, hark puts a sign-in link in Settings. It never reads the link aloud. Open it and sign in.
When the server shows ready, ask for what you want: “what can my docs server do?”

Up to 12 servers. They must be public https. Tokens go in Settings, never spoken. Your sign-in for each server stays in your Durable Object.

Approvals: your passkey, not your voice

Anyone in the room can talk to hark, and so can a web page it reads or an agent connected to it. Turn on Account › Biometrics for changes and words alone stop being enough. It is off until you turn it on; hark captures nothing at sign-in.

While it is on, these wait for your passkey (Face ID, Touch ID, Windows Hello or a security key): Cloudflare API calls that POST, PUT, PATCH or DELETE; terminal commands; file writes; code that deletes files; MCP tool calls and connections; changes to your instructions; and panel deletes. Turning it off needs the passkey too.

Ask for it: “delete the pasta-timer worker”.
hark shows a card with exactly what will run, and your device asks for your face, finger or PIN.
The passkey signs a hash of that one call. Your Durable Object checks the signature, the site, the user check and the counter, then runs it once.

Talk over hark, decline, or wait a minute, and nothing runs. Reads, timers, memories, voices and pictures never ask. There is no voiceprint and no face matching. While the setting is off, account changes still wait for a clear spoken yes.

Let your agents reach you

Planned. This section describes where hark is going. It is not built yet. SECURITY.md is the source of truth.

Your other agents and systems (my.ax, Pi, a terraloop, CI) can talk to you through hark. There are two doors. Both treat what they bring like a stranger in the room: hark will say it, but it can never approve anything.

Webhooks: the doorbell

For events that should reach you even when hark is asleep: a deploy finished, CI failed, a teammate answered.

In Settings, Webhooks, create a hook and name it, for example “CI: hark repo”. Pick what it may do: notify (default), store, or wake.
Copy the URL and secret. The secret is shown once.
Sign every request: an HMAC-SHA256 of the timestamp and raw body, in a header. Unsigned, old, or replayed requests are dropped.

POST https://<host>/hook/<hook id>
hark-timestamp: 1767225600
hark-signature: v1=<hex hmac of "timestamp.body">
content-type: application/json

{ "title": "CI failed on main", "detail": "3 tests", "level": "bad" }

What happens next depends on hark:

hark is	It
Listening	Says it at the next pause, from a template. Never over you.
In a turn	Waits for the turn to end.
Asleep	Queues it, sends a push notification, and tells you when you wake it.

notify speaks a template and never hands the payload to the model. wake starts a turn so hark can act, and anything gated still needs your passkey. Each hook has a rate limit, quiet hours, a delivery log, and can be rotated or revoked in Settings.

MCP: the conversation

hark is also an MCP server at https://<host>/mcp, so an agent can talk to it while it works.

Add the URL to your MCP client: Pi, Claude, chat.ax.
The client opens hark’s consent page. Sign in with Cloudflare and choose what it may do.
hark gives the client its own token. Your Cloudflare token never leaves your Durable Object.

Scope	Tool	What it does
`hark:tell`	`hark_tell(text)`	hark says it to you out loud. No model turn. The default.
`hark:read`	`hark_status`	Presence, timers, memories.
`hark:say`	`hark_say(text)`	Starts a turn as that agent and streams the reply back. Voice goes first.

A request for a gated action comes back as a pending task while your passkey decides. There is no approve tool. Settings, Connected agents lists every client with its scopes and last use, and revokes it at once. Every turn records whether it came from your voice or from which agent.

MCP events, while hark is awake

hark can subscribe to the MCP servers you connected and speak their updates as they happen, for example a ticket that changed state. That works only while hark is awake. Asleep, nothing is connected and nothing is billed, so events that must not be missed should also send a webhook. Webhooks wake hark. MCP lets it reply and fetch details.

What it costs

hark has no model bill of its own. It bills the account you pick. Flux is billed per minute of audio while hark is awake, so it sleeps after two quiet minutes and when you say goodbye. Aura is billed per character spoken. Asleep, nothing streams and nothing is billed.

Run your own

You need Bun, a Cloudflare account with a zone, npx wrangler login, and an OAuth client with the redirect URL https://<host>/oauth/callback.

git clone https://github.com/acoyfellow/hark && cd hark && bun install
cp deploy/example.conf deploy/mine.conf
bun run ship -- deploy/mine.conf

To work on it locally, against a fake Cloudflare with no sign-in:

bun run dev
bun run e2e

Limits

English only, because Flux and Aura 2 are English models.
Echo cancellation depends on your browser. Loud speakers can make it hear itself. A headset works best.
One tab at a time. A second tab takes the line over.
No wake word. Tap the ear or press space.
Timers speak only while hark is open. Otherwise it tells you the next time you wake it.

Talk to it. That is the manual.