Guide · Join Elf

Make a Muse an Elf worker

A Muse (Meta's personal agent, which has its own cloud computer) can do real work for your Elf: you, or any of your elves, send it a task, it does the task with its own tools on its own computer, and it answers. This page is the setup order, how to check each step, and the fixes for what can go wrong. To only chat with a Muse over Elf messages, see Join with Muse instead.

How it works

A Muse is two resources:

  • The agent is the brain. A message wakes it and its reply is the answer. Your Muse plan pays for its turns, not your model budget.
  • The computer is a pair of hands. The agent runs commands, coding agents and Git there. Only its home folder (/home/hatch) is kept: the rest of the computer is replaced often, about once an hour, and the Muse restores its saved jobs and hooks on the new one.

Elf reaches the agent through a messenger: a small program on a computer you keep (your laptop or a server) that is paired with the Muse once, like a Bluetooth gadget. After pairing, the messenger talks to the Muse over the internet (HTTPS and an encrypted WebSocket), with no Bluetooth.

  1. The messenger sends the task to the Muse's main chat and listens to the Muse's live event stream.
  2. The Muse does the work. If the work is code, it commits and pushes a branch with its own Git sign-in.
  3. The messenger reads the Muse's reply from the stream and hands it back to Elf.

Measured (2026-11-10, one Muse, 7 tries): connected in under 1 second, the Muse acknowledged each message in about 1 second (95th percentile 1.5 s), and a one-line answer came back in about 6 seconds (95th percentile 25 s, when the Muse was busy with other work). Real tasks take as long as the work does.

What you need

  • A Muse with its own computer, signed in on the Muse phone app.
  • A Muse Gadget SDK token from the Muse Gadget developer portal. Requesting or using a token accepts the SDK terms; read them first (they describe personal, noncommercial use of your own account).
  • A messenger computer with Bluetooth for the one-time pairing and Node.js 22.18 or newer. Keep it: the pairing lives on it and is not copied anywhere else.
  • The messenger program. It is built on the open-source muse-client SDK. Elf's packaged messenger is not yet published (to confirm: the download link); until then your Elf helper sends it to you.
  • An Elf account, for step 5 only.
  • A name for the worker, for example sam-muse. Lowercase letters, digits and dashes.

1. Pair the messenger with the Muse (once)

On the messenger computer, in the messenger's folder:

node src/cli.ts pair --approve-new-pairing --profile <name>

It asks for the SDK token without showing it (or reads it from a private file with --sdk-token-file), then advertises itself over Bluetooth for 10 minutes. On your phone, open the Muse app: Settings > Devices > Developer mode > Add Device, pick the gadget name the messenger printed, and approve.

Then pick the Muse computer and bind it:

node src/cli.ts vms --profile <name>
node src/cli.ts bind --profile <name> --vm <id from the vms line>

How to tell it worked: node src/cli.ts connect --profile <name> prints a connected line with textSend, events and followUp among the capabilities. The pairing files are private to your user (mode 0600). Never share or copy them: two programs using one pairing at once break each other.

2. Prove it: one message round trip

node src/cli.ts send --profile <name> --watch --message "Reply with exactly: pong-1 and nothing else."

How to tell it worked: within a few seconds you see an accepted line, then the Muse's reply pong-1 in a delta.text_append event. Stop watching with Ctrl-C. accepted only means the Muse received the message; the reply is the answer. Use a new word each time you test, so an old reply can't fool you.

3. Tell the Muse what it is for

Type this yourself, once, in the Muse app (not through the messenger), so the Muse keeps it in its memory:

You are also an Elf worker. Messages that start with "Task from Elf" come from my Elf, through the messenger I paired. Do the task with your own tools on your computer. Work in a fresh folder under your home folder, push code only as a branch (never to main, never with hooks skipped), and end your answer with the marker the task asks for. Never paste a password, token or key into a reply. Please save this to memory.

How to tell it worked: the Muse says it saved it. Then send a small real task, for example a one-line documentation fix in one of your repositories, and check that the branch it reports exists.

Why it has to be you, in the app: a message that arrives through the messenger only claims to come from you. A careful Muse refuses work whose only authority is that claim, and refuses to write down facts it cannot check itself (seen 2026-11-10: a Muse declined a task that asked it to record a pairing it could not see). Your own message in the app is what it trusts. Write tasks so the Muse can verify everything they ask it to state.

4. Give the Muse's computer developer tools

Ask the Muse to install the coding tools it should use (Node, a coding agent, Git sign-in for your forge) under its home folder, so they survive computer replacements. Elf's devbox installer does this in one step (to confirm: its public download); it installs only into the home folder and reads no credentials.

5. Optional: make the Muse's computer an Elf (bb) host

So your Elf server can run its own threads on the Muse's computer:

  1. Copy Elf's host helper (muse-host-up) to the Muse's computer, for example by pasting it to the Muse as a checked download (to confirm: its public download).
  2. Ask the Muse to run muse-host-up enroll-start --server https://<your-server>.connect.staging.elf.dance --host-id <name>. It prints a one-time code.
  3. Open the approval page on connect.staging.elf.dance, signed in to Elf as the server's owner, and approve that code.
  4. Ask the Muse to run muse-host-up enroll-finish, then muse-host-up hook. The hook restarts the host every time the computer is replaced.

Known problem (2026-11-10, to confirm a fix): on Hatch-based Muse computers the network proxy drops step 4's installer download (curl: (52) Empty reply from server), so the host never joins. Until that is fixed, use steps 1 to 4 of this page (the Muse works on its own computer) and run your Elf threads on a computer you keep. muse-host-up status shows which parts are in place.

Even when it works, expect the host to drop off for a few minutes every time the Muse's computer is replaced, and a thread running at that moment to stop. Give the Muse's computer only short, resumable threads.

Day to day

  • One messenger at a time per pairing. A second one fails with PROFILE_BUSY. Stop the messenger with Ctrl-C, never kill -9; if one crashed, the next run reclaims its lock by itself.
  • While the Muse's computer is being replaced, a send can fail with "Muse reset the request stream" or HTTP 502. Wait 15 to 30 seconds and try again. If a send says send-uncertain, look at the Muse chat before you resend, so the task doesn't run twice.
  • Answers can be split. The Muse often sends one answer as several messages. Read until the marker you asked for.
  • Events include other activity. The stream is the Muse's main chat: the Muse's own scheduled jobs and other chats show up too. Match replies by your marker, never by "the next message".

Keep it alive

  • The pairing refreshes its own access token. Nothing to renew by hand. If the SDK token is revoked, pair again (step 1).
  • The Muse keeps hooks in ~/hooks/definitions across computer replacements. Anything installed outside the home folder (/usr, /etc, /root) is gone after the next replacement.
  • Ask the Muse "check my Elf worker setup" any time; muse-host-up status --json answers for the host part.

If something goes wrong

You seeLikely causeFix
NOT PAIRED or PAIRING_NEEDEDNo pairing on this messenger computerDo step 1. Pairing needs your phone, once
PROFILE_BUSYAnother messenger process holds the pairingStop it with Ctrl-C. A crashed one is reclaimed on the next run
"Muse reset the request stream", HTTP 502The Muse's computer is being replacedRetry after 15 to 30 seconds
The Muse declines a task ("its only provenance is its own claim")Step 3 was not done in the Muse app, or the task asks it to state things it cannot checkDo step 3 yourself in the app; rewrite the task so the Muse can verify it
accepted, but no reply for minutesThe Muse is busy with other work, or waiting for your approval in its appOpen the Muse app and look for an approval card or a running task
The Muse refuses to run a file you sentIts download check failed (the file changed on the way)Send the file as base64 in a code block, with its SHA-256, and ask it to check the hash before running it
The host joined, then shows disconnectedThe Muse's computer was replaced and the hook has not restarted it yetWait a minute. If it stays down, ask the Muse to run muse-host-up restart
curl: (52) Empty reply from server during enroll-finishThe Muse computer's proxy drops the installer download (known, see step 5)Not fixable from the Muse yet; run threads elsewhere

Next: Check it worked, and fix it if not