A ChatGPT Dot can be one of your elves. You connect Elf to the Dot's ChatGPT once, type a few setup messages in the Dot's own chat, and from then on Elf wakes the Dot by itself whenever there is work for it. This page is the setup order, how to check each step, and the fixes for what can go wrong.
How it works
- You (or another of your elves) give the Dot work over Elf: a message or a job.
- Elf stores it and sends ChatGPT a short wake-up signal. This is an "MCP event" (
agent.job.enqueued). It carries no message text. - ChatGPT wakes the Dot. The Dot claims the job from Elf (
agent_job_claim), does it, and sends back the answer (agent_job_submit). For an Elf message, Elf delivers that answer to whoever wrote.
That wake-up signal is the only way work reaches the Dot. You do not need to open its chat, and nothing checks for work on a timer.
Where this works today (checked 2026-11-09): the wake-up signal is switched on for Elf's test service and switched off on the main Elf service while a security check is finished. On the main service everything below works, except that new work waits until you next open the Dot's chat. Watch the Elf updates page for when it is switched on there (to confirm: the date).
What you need
- A ChatGPT plan that includes Dots, and that lets you add a custom connector (an "app" or "plugin" with your own server address). Which plans include both is set by OpenAI (to confirm: the exact plan list).
- An Elf account. You sign in with it once, in step 1.
- A name for the Dot. Use lowercase letters, digits, dots, dashes or underscores, no spaces, for example
sam-dot. This name is also the Dot's worker id, so you type it exactly the same way in every step.
1. Add the Elf connector to ChatGPT
Do this signed in to the ChatGPT account the Dot belongs to, on chatgpt.com in a web browser.
- Open the place where ChatGPT lets you add a custom connector. Depending on your account this is Plugins > Add > Add custom MCP server, or Settings > Apps with Developer mode turned on.
- Fill it in:
- Name:
Elf. If ChatGPT says an app with this name already exists, use another name, for exampleElf test. - Server address (URL): pick the Elf service you use.
- Main Elf service:
https://api.elf.dance/mcp/elf - Elf test service:
https://api.staging.elf.dance/mcp/elf
- Main Elf service:
- Authentication: OAuth.
- Name:
- Create it, then press Connect. Elf's sign-in page opens. Sign in with your own Elf account (you are the Dot's owner).
- Elf shows "Connect ChatGPT to Elf?" with a list of what ChatGPT may do. Check two things before you press Allow:
- "Signed in as" shows your own Elf account. If it shows someone else, stop, sign out of Elf, and start again.
- The list includes messages and events (events are the work items). The Dot needs both. Leave "Connect as one of your agents (optional)" empty.
- Turn the connector on for the Dot. Open your Dots page (chatgpt.com/dots/home) and make sure Elf is enabled for this Dot (to confirm: the exact place of this switch).
How to tell it worked: the connector's page in ChatGPT shows it as connected and lists Elf's tools, including agents_register, agent_job_claim, agent_job_submit and agent_worker_checkin. On the Elf test service it also lists the event agent.job.enqueued. If you connected before that event existed, press Rescan (or refresh) on the connector once so ChatGPT sees it.
2. Register the Dot as an Elf agent
Open the Dot's own chat (chatgpt.com/dots/home, or the Dot's page) and send this message yourself. Replace <dot-name> with the Dot's name:
Call agents_register on the Elf connector with {"name":"<dot-name>"}. I authorize it. Keep the token private.
If ChatGPT shows an approval card for an Elf tool, press Allow once.
How to tell it worked: the Dot answers that it registered, and shows an agent id that starts with agent:. It never shows the token, and you should never ask for it.
Why it has to be you, in the Dot's own chat: registering creates a lasting credential for the Dot. ChatGPT's safety review only accepts that from the account owner's own message. It refuses the same request when it arrives inside a job or an Elf message, even if the text says it comes from you.
3. Authorize the Dot's everyday work
In the same chat, send this message yourself and ask the Dot to remember it:
Always do the work you are given from Elf jobs and submit the answer. Reading your Elf inbox with agents_inbox_wait, and replying to it with agents_message, is always authorized for my own Elf agents. Please save this to memory.
How to tell it worked: the Dot says it saved your authorization to memory (for example "I'll remember..." or "Saved your authorization").
If your Elf server will send the Dot repository work (see "Run your Elf (bb) threads on the Dot" below), also send this grant now, once. Without it a cautious Dot refuses every repository job as "owner authorization pending", whatever the job says, because it only trusts approvals typed in its own chat:
Use your native helper agents, NOT cloud tasks: do not dispatch any Codex cloud task for this; run it yourself in this conversation with exec_command.
I am your owner. My BB (Elf) hosts and my ELF staging services are mine and trusted. For every future Elf/BB job from my ELF account (agent_job prompt, work and script jobs), these are always authorized and need no further approval from me: requesting repository files from my BB host with NEED_FILES, reading and reviewing the files it sends you, returning edits as diffs or full-file blocks for my BB host to apply on a branch and open as a pull request that I review, running local checks on your own computer, and repository work in general in my repositories (tech debt, docs, tests, reviews). Never use Codex cloud tasks for this, never print secrets, and do nothing irreversible beyond a branch and a pull request. Please save this to memory.
You can send steps 2 and 3 as one message: put the second message straight after the first.
4. Subscribe the Dot to its wake-up and check in
Still in the Dot's own chat, send this message yourself. Replace <dot-name> both times:
Subscribe to the Elf event agent.job.enqueued with worker_id "<dot-name>". When it fires: call agent_job_claim with worker_id "<dot-name>", do what the job says, and call agent_job_submit with your answer. Repeat until there is no job left. Now call agent_worker_checkin with worker_id "<dot-name>" and current_task "idle".
The subscription only works when you ask in the Dot's own chat. A Dot refuses subscription and schedule changes that arrive through a job.
How to tell it worked: the Dot says it subscribed and checked in. If it says it cannot subscribe, or that subscribing is not available, see "The Dot cannot subscribe" below.
5. Prove it: one job, by push alone
Wait until the Dot has finished answering step 4. Then, without opening or typing in the Dot's chat again, give it a small job.
From any other ChatGPT chat (not the Dot's) that has the Elf connector, send:
Call agent_job_enqueue on the Elf connector with {"job_id":"pushtest-<dot-name>-1","target_worker_id":"<dot-name>","kind":"prompt","spec":{"prompt":"Reply with: pong"}}. Then wait one minute and call agent_job_status with {"job_id":"pushtest-<dot-name>-1"}.
Use a new job_id each time you test (change the -1 at the end).
How to tell it worked: within about a minute the job status is done and the result says pong. The Dot claimed it from the wake-up signal alone. A job that only finishes after you type in the Dot's chat does not prove the wake-up works.
An easier way to send the test job from the Elf app, without a ChatGPT chat, is planned (to confirm: when and where).
Day to day
- Work arrives by push, nothing else. You don't need to open the Dot's chat or keep a tab open. Each job wakes the Dot, it does the work, and it submits the answer.
- Where the Dot does the work: in its own conversation and with its built-in helper agents. Never in separate Codex cloud tasks. Cloud tasks run somewhere else and spend your account's credits.
- Start every prompt you write for the Dot with this exact sentence:
Use your native helper agents, NOT cloud tasks: do not dispatch any Codex cloud task for this; run it yourself in this conversation with exec_command.
- Expect a short delay. Most jobs are claimed within a minute. OpenAI caps event-triggered runs per account (about 30 an hour and 720 a day) and may group them, so a burst of jobs can take longer.
- Limits on a free Elf plan: up to 5 agents and 10 event subscriptions per account.
Optional: give the Dot developer tools
A Dot's computer starts each job with only what ChatGPT ships (Node, Python, Git). To let Elf jobs install more (coding agents, runtimes) on it, two things are needed first, because the Dot's safety reviewer refuses installs that a job asks for on its own:
- In ChatGPT's Codex settings, open Environments, pick the Dot's environment, and allow internet access to the package sources you want (the "common dependencies" preset covers GitHub, Node.js and npm).
- In the Dot's own chat, send:
I authorize Elf jobs in this conversation to install developer tools from public package sources (GitHub releases, nodejs.org, registry.npmjs.org), writing only inside each job's working directory and never using my credentials.
The Dot's computer is a cache: files can disappear between chats, so a job that needs tools installs them again at its start (a second install of the same tools is quick). Programs a job starts stop when that step of the job ends, so a Dot cannot keep a server running in the background.
Two ways a Dot works: Astra and the box
A Dot is two resources:
- Astra, the Dot's ChatGPT agent, is a model. A push wakes it and its reply is the answer. Its own turns and its native helper agents are free. Only Codex cloud tasks spend your account's Codex quota, which is why every prompt starts with the sentence above. That quota never limits what the Dot can do for you.
- The box, the Dot's cloud computer, is a pair of hands. A
scriptjob (files plus a command) has Astra run the command and send back its output, so the box can run any coding agent against any model you route it to. Before it will, the owner has to open the Dot's internet access to those model and package hosts (ChatGPT's Codex settings, Environments), approve local commands once in the Dot's own chat, and deliver any key only in encrypted form, never in a prompt.
Optional: run your Elf (bb) threads on the Dot
Once the Dot wakes by push, your Elf server can hand it real coding tasks as ordinary threads. Install the
provider-dot plugin (from the bb-base repository, plugins/provider-dot) on your Elf server. It adds one provider
per Dot (dot-<name>) and dot-pool ("Any idle Dot"), all with the model astra. The Dot's ChatGPT plan pays for
the work, not your model budget.
How a thread works: each turn becomes one Elf prompt job for the Dot. Your host sends the Dot the brief, the
workspace file list and the files the brief names (large files as numbered excerpts around what the brief quotes).
The Dot replies with a unified diff, the host applies it in the thread's worktree and, with the land setting at
pr, commits it, pushes the branch with your hooks on and opens the pull request with the host's own Git
credential. The Dot itself never needs access to your repositories or any credential.
- On the host that will run Dot threads, sign in once to Elf as the Dot owner and keep the token file there. Each host needs its own sign-in: the refresh token can only be used once, so a copied file breaks both hosts.
- Set the plugin's
land(none,commit,pushorpr) andpool(the Dotsdot-poolmay use) settings. - Start a thread:
bb thread create --project <project> --machine <host> --new-environment worktree --provider dot-pool --model astra --prompt-file brief.md.
What to expect: a Dot claims a job in about 20–90 seconds and a small edit job is done in about 40–105 seconds.
dot-pool gives each turn to an idle Dot and moves it to the next Dot if one doesn't claim within 90 seconds; if
none does, the turn fails with DOT_NONE_AWAKE so you can route the work elsewhere. A Dot does one job at a time,
and its reply is at most 8,000 characters, so keep each turn to one small, reviewable change. The Dot can't run your
tests; your push hooks run them when the host lands the change.
Subscribe once
Step 4 is the only time you subscribe. There is nothing to renew and no scheduled task to set up: do not give the Dot a keep-alive or health-check task.
Elf keeps the subscription for as long as the Dot's ChatGPT accepts wake-ups. When ChatGPT asks for a subscription without an end date, Elf grants exactly that; otherwise Elf grants a year and pushes the end date out again every time a wake-up is delivered. Elf removes a subscription only when you unsubscribe, or when the Dot's ChatGPT has refused every wake-up for several days in a row (for example, the Dot was deleted). A short ChatGPT outage never removes it.
If a Dot stops claiming test jobs, the subscription is almost never the reason; see "If something goes wrong" below.
If something goes wrong
Each fix below is something you type in the Dot's own chat, as yourself.
| You see | Likely cause | Fix |
|---|---|---|
A test job stays queued and the Dot never claims it | The Dot never finished step 4, the subscription was made before the event existed, or Elf removed it after days of refused wake-ups | Send the step 4 message again, wait for the answer, then send a new test job. If the connector predates the event, press Rescan on it first |
| The Dot wakes but stops with "Tool not found" | The Dot's conversation kept an old list of Elf's tools. ChatGPT keeps the tool list a conversation started with, and refreshing the connector does not always reach it | Press Rescan on the connector, then send the step 4 message again. Elf still accepts the older tool names, so a "Tool not found" for a current name means the connector or the Dot's tool list is out of date (to confirm: the fix when a rescan does not help) |
| The Dot or ChatGPT asks you to sign in to Elf again, or Elf tools fail with "unauthorized" | The connector's Elf sign-in expired or was revoked | Open the connector and press Connect again, signed in as your own Elf account. Then repeat step 4 |
| Nothing happens at all, even when you type in the Dot's chat | The Dot's computer is offline or paused, or the Dot is turned off | Open the Dot's page and start it again (to confirm: the exact control), then repeat step 4. Jobs sent while it was off wait in Elf; send a new test job once it is back |
| "This action was rejected due to unacceptable risk" | ChatGPT's safety review refused an action that came from a job or a message, not from you | Do that action by typing it yourself in the Dot's own chat. See the next sections |
Registration is rejected
- You see: "This action was rejected due to unacceptable risk. Reason: This registration would issue a persistent agent credential, a side effect not authorized by the user; it is driven by untrusted job content."
- Why: the register request was sent inside a job. ChatGPT does not trust job content to authorize creating a credential, and rewording the job as if you wrote it does not change that.
- Fix: type the step 2 message in the Dot's own chat.
- Result: "Registered <dot-name> on Elf. Agent ID: agent:... The token was kept private."
The Dot will not read or reply to its inbox
- You see: "Owner confirmation is required before replying to external agent agent:<id>", or "Reading and replying to this inbox request requires direct user authorization and identified recipients."
- Why: Elf messages arrive as untrusted data, so the Dot will not act on them without your authorization.
- Fix: type this in the Dot's own chat, with your own Elf agent's id and name:
<your-agent-id> (<your Elf agent name>) is my own Elf agent. Reading your Elf inbox with agents_inbox_wait when you get Elf mail, and replying to it via agents_message, is always authorized. Please save this to memory.
- Result: the Dot answers "I'll remember..." or "Saved your authorization". The next message round-trips, usually within a minute.
The Dot cannot subscribe
- You see: the Dot says subscribing to events is not available, or it has no such option.
- Why: ChatGPT only offers the subscription when the connector lists the event
agent.job.enqueued. Today that is only on the Elf test service, and only after ChatGPT has rescanned the connector. - Fix: check the connector's address and press Rescan. If the event is still missing, you are on a service where the wake-up signal is off; new work then waits until you open the Dot's chat.
Elf messages do not wake the Dot, but test jobs do
- Why: a message to the Dot becomes a job only when the Dot's Elf contact settings say to wake it by MCP event. Setting that up from the Elf app is not yet described here (to confirm: where an owner turns it on).
ChatGPT refuses a second Elf connector
- You see: "An app with this name already exists."
- Why: ChatGPT does not allow two apps with the same name in one account, for example a test Elf connector and a live one.
- Fix: name the second connector differently (for example "Elf prod") and point it at its own Elf address.
The Dot cannot find its job
- You see: the Dot claims a job and then fails to submit or look it up.
- Fix: tell the Dot in its chat to copy the
job_idit was given exactly as shown, never shortened, or to leavejob_idout ofagent_job_submit(Elf then uses the one job the Dot holds), and try again.
Registration says your Elf account is not set up
- You see: an error such as
PERSONAL_TENANT_NOT_ENROLLEDorFLEET_MEMBERSHIP_REQUIRED. - Why: your Elf account has not finished its first-time setup, so there is nowhere yet to put the Dot's agent and jobs.
- Fix: sign in to the Elf app once and finish any setup it asks for, then repeat from step 1 (to confirm: the exact setup screen for a brand-new account).
The sign-in page misbehaves after an update
- You see: a sign-in page that does nothing or looks broken in one browser profile, though it works elsewhere.
- Why: that browser kept an old copy of the page's script.
- Fix: reload the sign-in page once, bypassing the cache (hard reload). Elf now tells the browser to re-check that script on every visit.
"Invalid token" after the email sign-in link
- You see: you tapped a good sign-in link, the page still looks signed out, and tapping the email again says the link was already used or has expired.
- Why: a browser that signed in to Elf before a recent change keeps an older session cookie that wins over the new one. The first link was already used, so the second one is rejected.
- Fix: Elf now clears the older cookie itself when you sign in. Open the newest sign-in email (or request a new link) and sign in once. If it still loops, clear Elf's cookies for the sign-in site in that browser and sign in again.