This 📝buildbook lets any AI agent help a person install the MythOS device runner on their Mac, enroll it with MythOS so it can run their loops, fix the known setup problems, and write up anything that still goes wrong as a report to MythOS. The runner is a small program that checks in with MythOS every few minutes and runs loops on the person's own computer and AI subscription. This guide replaces guessing: the agent checks the machine first, so the one-time code is used only when everything is ready.

Paste this into the AI of your choice:

Help me set up the MythOS device runner on this computer. Read https://mythos.one/me/mythos/ffdddc and walk me through it step by step, and if anything goes wrong, help me write it up and send it to MythOS.

Prerequisites

A Mac. The installer stops on anything else ("supports macOS for now"). Apple Silicon and Intel both work; Intel needs extra steps for tmux.
A MythOS account on the Oracle plan. Devices and loops are Oracle features; an account without it is refused with TIER_REQUIRED.
Apple's Command Line Tools, which bring python3 (3.9 or later is required).
A python3 that can open https://mythos.one with a verified connection. Python from python.org often cannot until its certificates are installed.
To run loops (not just check in): Claude Code (claude) and tmux. Without them the device enrolls "heartbeat only" and can be finished later. Codex (codex) is optional and is added as an account.
A terminal the person types in themselves. Setup may open a browser sign-in and ask the person to paste a token; an agent's own shell has no keyboard for that.
No administrator password is needed for the runner itself. MacPorts (Intel only) does need one.

Discovery

Inventory. Before the person opens a code, run the preflight script in Reference Implementation (read-only, safe to re-run) and answer:

CPU (uname -m): arm64 (Apple Silicon) or x86_64 (Intel)?
macOS version (sw_vers -productVersion).
Command Line Tools present (xcode-select -p prints a path)?
Which python3 comes first, its version, and can it open https://mythos.one with verified TLS?
Are claude and codex installed, and signed in?
Is tmux installed? Is Homebrew (brew) or MacPorts (port) present?
Is the runner already installed (~/.mythos/bin/mythos-device version)? If so, skip to Quickstart step 5.

Interview (only where the inventory leaves it open):

"Is this machine always on, or a laptop that sleeps?" Decides the check-in interval chosen in Add device.
"Which folders hold the projects your loops will work in?" Decides which folders to trust (Quickstart step 7).
"Should this machine take any loop that doesn't name a device, or only loops pinned to it?" Decides the Unpinned loops setting.
On Intel with no tmux: "MacPorts (needs your password) or a no-password build from source?"

Plan. Tell the person what is missing, fix each item (Troubleshooting has the exact fix), re-run the preflight, and only then go to Quickstart step 3. Get their OK before installing anything.

Quickstart

Preflight. Run the preflight script. Every line should read ok except tmux and sign-in notes, which can be finished later. Fix any FIX line first.
tmux, if missing. Apple Silicon: install Homebrew from https://brew.sh, then brew install tmux. Intel: Homebrew refuses Intel Macs; use MacPorts (sudo port install tmux) or the source build in Reference Implementation. Check: command -v tmux || ls ~/.local/bin/tmux /opt/local/bin/tmux.
Open the code only now. The person opens MythOS › Agents › Devices › Add device, names the machine (this name, not the computer's own name, is what MythOS shows), and copies the install line. The code lasts ten minutes and works once.
Install. The person pastes the line into their own Terminal: curl -fsSL https://mythos.one/install/device | sh -s -- --code XXXX-XXXX. It downloads the runner, checks its checksum, installs it, adds ~/.mythos/bin to the PATH, and runs setup. Re-running it is safe: an installed version is not downloaded again, and an enrolled device is not enrolled twice (the code is not used).
Resume or finish setup. Open a new Terminal window and run ~/.mythos/bin/mythos-device setup. With no code it resumes from where it stopped: schedules the check-in, re-checks prerequisites, turns run claiming on when Claude Code and tmux are present, and signs Claude Code in for background runs. If it says to, run ~/.mythos/bin/mythos-device sign-in in the person's own Terminal.
Turn on running. ~/.mythos/bin/mythos-device runner enable (safe if already on).
Trust project folders. Claude Code asks "Do you trust this folder?" once per project, per account, and an unattended run cannot answer it. For each project folder the runner will work in, the person runs cd <project folder> && claude (or, for a named account, cd <project folder> && CLAUDE_CONFIG_DIR=<that account's folder> claude), chooses "Yes, I trust this folder", then types /exit. If ~/.mythos/bin/mythos-device trust list works on this runner, also run ~/.mythos/bin/mythos-device trust add <folder holding the projects>. Then run ~/.mythos/bin/mythos-device account finish (add a label for a named account) to clear Claude Code's first-run screens.
Check the machine. ~/.mythos/bin/mythos-device doctor should end with Ready to run loops. "Design access" is optional.
Check MythOS. Agents › Devices should show the device as healthy. With MythOS MCP, the extended tool list_devices should show status: healthy, readiness.tmux: true, and readiness.runnerEnabled: true.
Settings. On the device's page, walk the person through Edit Settings, starting with Unpinned loops (off by default for new devices). The public 📝Devices memo explains each setting.

Reference

Install locations. Each version lives in ~/.mythos/device/<version>; ~/.mythos/bin/mythos-device points at the current one. Device state lives under ~/.mythos/device. Keys are stored in the login Keychain and are never printed. Agents must not open the runner's config or secret files.
PATH. The installer adds one marked line to ~/.zprofile (zsh) or ~/.bash_profile (bash), once. Until a new Terminal opens, use the full path ~/.mythos/bin/mythos-device.
Check-ins. A launchd job (com.mythos.device-heartbeat) runs every 60 seconds and sends a heartbeat when due: every 300 seconds unless a different interval was chosen. The device shows healthy without a Terminal open. Updates install themselves on later ticks.
Finding tools. Besides the PATH, the runner looks in /opt/homebrew/bin, /usr/local/bin, and ~/.local/bin. The check-in job keeps the PATH from the Terminal where setup last ran, so run setup again from a new Terminal after installing tmux somewhere else (such as MacPorts' /opt/local/bin).
Ready to run loops means: Command Line Tools, Claude Code and tmux present, Claude Code signed in for background runs, and run claiming on. Anything less is "Heartbeat only — N steps left".
Accounts. A device can hold several agent accounts, each in its own folder: mythos-device account add <label> --config-dir <folder> (add --agent codex for Codex, then sign in with CODEX_HOME=<folder> codex login). The person signs each account in themselves. account list shows them; account finish [<label>] opens the agent to clear its first-run, folder-trust and permission screens.
Plug-ins. Plain loops need none. mythos-device plugin add <name> <command> hands runs that require a named capability to a command; plugin list shows them.
Device page. Agents › Devices › the device (https://mythos.one/agents/devices/<device id>): health, Edit Settings (Name, Interval, Alerts, Retention, Unpinned loops, Max sessions, Capacity) and Keys (what loop runs may do in MythOS, and Claim loop runs to pause the machine).
Unpinned loops (takeUnpinnedLoops): off means the device takes only loops whose Device names it.
Naming. Name each device for the machine it is; with several devices, a wrong name sends loops to the wrong place.
Codes. Ten minutes, single use. MythOS marks a code used the moment it receives a valid one, even if setup then fails afterward.

Reference Implementation

Preflight (read-only; save as ~/mythos-preflight.sh, run sh ~/mythos-preflight.sh):

#!/bin/sh
echo "CPU: $(uname -m)   macOS: $(sw_vers -productVersion)"
if xcode-select -p >/dev/null 2>&1; then echo "ok   Command Line Tools"; else echo "FIX  Command Line Tools: xcode-select --install"; fi
echo "python3: $(command -v python3 || echo missing) $(python3 --version 2>&1)"
if python3 -c 'import sys; sys.exit(0 if sys.version_info >= (3, 9) else 1)' 2>/dev/null; then echo "ok   Python 3.9+"; else echo "FIX  Python 3.9 or later"; fi
if python3 -c "import socket,ssl; ssl.create_default_context().wrap_socket(socket.create_connection(('mythos.one',443),timeout=15),server_hostname='mythos.one').close()" 2>/dev/null; then echo "ok   python3 opens https://mythos.one (verified)"; else echo "FIX  python3 cannot open https://mythos.one with verified TLS"; fi
for t in claude codex tmux brew port; do
  p=$(command -v "$t" 2>/dev/null || ls /opt/homebrew/bin/$t /usr/local/bin/$t "$HOME/.local/bin/$t" /opt/local/bin/$t 2>/dev/null | head -1)
  echo "$t: ${p:-not found}"
done
command -v claude >/dev/null 2>&1 && { echo "claude sign-in:"; claude auth status 2>&1 | head -3; }
command -v codex >/dev/null 2>&1 && { echo "codex sign-in:"; codex login status 2>&1 | head -2; }
if [ -x "$HOME/.mythos/bin/mythos-device" ]; then echo "runner: $("$HOME/.mythos/bin/mythos-device" version)"; else echo "runner: not installed"; fi

tmux from source on an Intel Mac (tested on one Intel Mac, 2026-10-29; no password; compare each download's SHA-256 with the one its release page publishes before building). Save as ~/tmux-build.sh and run sh ~/tmux-build.sh, rather than pasting it line by line:

#!/bin/sh
set -eu
if [ -x "$HOME/.local/bin/tmux" ]; then echo "tmux already at ~/.local/bin/tmux"; exit 0; fi
B="$HOME/tmux-build"; mkdir -p "$B"; cd "$B"
curl -fLO https://github.com/libevent/libevent/releases/download/release-2.1.13-stable/libevent-2.1.13-stable.tar.gz
curl -fLO https://github.com/tmux/tmux/releases/download/3.8/tmux-3.8.tar.gz
shasum -a 256 libevent-2.1.13-stable.tar.gz tmux-3.8.tar.gz
tar -xzf libevent-2.1.13-stable.tar.gz
(cd libevent-2.1.13-stable && ./configure --prefix="$B/deps" --disable-shared --disable-openssl && make && make install)
tar -xzf tmux-3.8.tar.gz
cd tmux-3.8
PKG_CONFIG=/usr/bin/false LIBEVENT_CFLAGS="-I$B/deps/include" LIBEVENT_LIBS="$B/deps/lib/libevent_core.a" LIBNCURSES_LIBS=-lncurses ./configure --prefix="$HOME/.local" --disable-utf8proc --disable-jemalloc
make && make install
"$HOME/.local/bin/tmux" -V

Exact Commands & Payloads

Install and enroll: curl -fsSL https://mythos.one/install/device | sh -s -- --code XXXX-XXXX
Install with Apple's Python instead of python.org's: curl -fsSL https://mythos.one/install/device | PATH="/usr/bin:$PATH" sh -s -- --code XXXX-XXXX
Resume setup: ~/.mythos/bin/mythos-device setup
Re-enroll an enrolled device with a fresh code: ~/.mythos/bin/mythos-device setup --code XXXX-XXXX --url https://mythos.one --replace
Check: ~/.mythos/bin/mythos-device doctor · Version: ~/.mythos/bin/mythos-device version
Running: ~/.mythos/bin/mythos-device runner enable · runner disable · runner status
Background sign-in: ~/.mythos/bin/mythos-device sign-in
Send a check-in now: ~/.mythos/bin/mythos-device heartbeat
Accounts: ~/.mythos/bin/mythos-device account add work --config-dir ~/.claude-work · account list · account finish work
Plug-ins: ~/.mythos/bin/mythos-device plugin list
Python certificates (python.org builds): open "/Applications/Python 3.14/Install Certificates.command" (match the folder name: ls /Applications | grep Python)
Intel tmux via MacPorts (after installing MacPorts from https://www.macports.org): sudo port install tmux
Remove: ~/.mythos/bin/mythos-device uninstall (add --forget to delete the device from MythOS too)

Troubleshooting

Setup failed: exchange failed (URLError). The code is spent… → the request never got a reply. Usually python.org Python has no certificates (the preflight TLS line fails). → Run Install Certificates.command, or install with Apple's Python (Exact Commands). The message is not always true: if the failure happened before connecting (a certificate, DNS or network error), MythOS never saw the code and the same line works again within its ten minutes. If it then says INVALID_CODE, or the ten minutes are up, open a fresh code from Add device.
Setup refused: HTTP … INVALID_CODE → the code expired or was already used. → Open a fresh code and run the new line.
Python 3.9 or later is required → no Command Line Tools. → xcode-select --install, then run the same line again (the code was not used).
Refused: this device is already enrolled → already done. → ~/.mythos/bin/mythos-device setup to resume; --replace with a fresh code only to start over.
Missing tmux / "Heartbeat only" → tmux not installed. → Quickstart step 2, open a new Terminal, then mythos-device setup and mythos-device runner enable.
Homebrew on macOS is only supported on Apple Silicon processors! → Intel Mac. → MacPorts or the source build.
mythos-device: command not found → the PATH change applies to new Terminals. → Open a new window or use ~/.mythos/bin/mythos-device.
Background-run sign-in: run mythos-device sign-in → setup had no keyboard to sign in with. → The person runs ~/.mythos/bin/mythos-device sign-in in their own Terminal.
Doctor says can't read the Keychain from here → doctor ran inside an agent's session. → The person runs doctor in their own Terminal; the device page is authoritative.
A run stops on "Do you trust this folder?" or a first-run screen → that project or account was never opened once. → Quickstart step 7.
No run key is stored → enrollment did not finish storing keys. → Fresh code, then the re-enroll command.
TIER_REQUIRED → the account is not on Oracle.
Device shows silent or failing → ~/.mythos/bin/mythos-device heartbeat, then doctor, and fix each FIX line.
The device never picks up loops → Unpinned loops is off and no loop names this device. → Pin the loop to the device, or turn Unpinned loops on.
The settings link printed at the end of setup doesn't open → use Agents › Devices in MythOS instead.

Reporting a Problem to MythOS

If something here didn't work, draft a report with the person, show it to them, and send it only with their OK. Use this shape:

Objective: one bolded sentence: what you were doing and what broke.
Environment: runner version, Mac type (Apple Silicon or Intel), macOS version, Python version and where it came from, Claude Code or Codex version, what was present and missing, and whether an agent drove the install.
Timeline: numbered steps with times, each with the exact message seen.
One section per issue: steps to reproduce, the exact error text, root cause if known (say "unverified" when it is), the workaround that worked, and a suggested fix.

Never include codes, keys, tokens, passwords, the contents of config or Keychain files, email addresses, or the person's username inside paths (write ~ for the home folder). Include the device name only if the person agrees.

To send it: the person opens https://mythos.one/contact, chooses the topic Bug report, and pastes the report as the message (5,000 characters at most; trim the timeline if needed). Or email it to [email protected].