Executor

Operate Rhys Sullivan's Executor as a pinned Central service on Flagg. This is not generic Executor advice. The local target is the repo-owned LaunchDaemon in joelclaw-central, running as the existing joelclaw service account with explicit state and log directories.

Use system-architecture too when the task changes Central topology, service ownership, gateway exposure, or Flagg vs NAS placement. Use three-body only when Joel explicitly asks about NAS placement or storage.

When To Use

Use this skill when Joel mentions:

• Executor
• rhyssullivan/executor
• executor daemon
• Central Executor
• task execution service
• port 4788
• /Users/Shared/joelclaw/data/executor
• Executor database, storage, state, logs, or launchd wiring

Current Central Contract

Host:

• Run Executor on Flagg, not three-body.
• Keep it a native macOS launchd service, not a Docker container and not an Executor-installed background service.
• Supervise it with the repo-owned system LaunchDaemon.

Service shape:

• LaunchDaemon label: com.joelclaw.central.executor
• Easy dashboard LaunchDaemon label: com.joelclaw.central.executor-dashboard
• Service user: joelclaw
• Raw daemon bind: 0.0.0.0:4788
• Easy dashboard bind: 0.0.0.0:4789
• Primary easy dashboard URL: http://joels-mac-studio.tail7af24.ts.net:4789/
• Optional root easy dashboard URL: http://flagg.tail7af24.ts.net:4789/
• Local URL: http://127.0.0.1:4788/
• LAN URL: http://192.168.1.10:4788/
• Tailnet app-node URL: http://100.99.76.47:4788/
• Tailnet MagicDNS URL: http://joels-mac-studio.tail7af24.ts.net:4788/
• Optional root Tailscale node URL: http://100.127.252.116:4788/ / http://flagg.tail7af24.ts.net:4788/
• Pinned package version at time of service creation: executor@1.5.12
• Wrapper: /Users/Shared/joelclaw/bin/central-executor
• Installed package prefix: /Users/Shared/joelclaw/opt/executor/1.5.12
• State: /Users/Shared/joelclaw/data/executor
• Config/scope: /Users/Shared/joelclaw/etc/executor
• Logs: /Users/Shared/joelclaw/logs/executor
• Easy dashboard logs: /Users/Shared/joelclaw/logs/executor-dashboard

Central source files:

/Users/joel/Code/joelhooks/joelclaw-central/infra/launchd/bin/central-executor
/Users/joel/Code/joelhooks/joelclaw-central/infra/launchd/bin/central-executor-dashboard
/Users/joel/Code/joelhooks/joelclaw-central/infra/launchd/com.joelclaw.central.executor.plist
/Users/joel/Code/joelhooks/joelclaw-central/infra/launchd/com.joelclaw.central.executor-dashboard.plist
/Users/joel/Code/joelhooks/joelclaw-central/infra/config/executor/executor.jsonc
/Users/joel/Code/joelhooks/joelclaw-central/scripts/executor-dashboard-proxy.mjs
/Users/joel/Code/joelhooks/joelclaw-central/scripts/install-executor-launchdaemon.sh
/Users/joel/Code/joelhooks/joelclaw-central/scripts/apply-executor-slice.sh
/Users/joel/Code/joelhooks/joelclaw-central/scripts/open-executor-dashboard.sh
/Users/joel/Code/joelhooks/joelclaw-central/scripts/verify-executor-runtime.sh

Database And State

Executor has multiple database shapes depending on deployment mode:

• Local CLI daemon: libSQL/SQLite under EXECUTOR_DATA_DIR, normally data.db plus WAL/SHM files.
• Self-host container: libSQL/SQLite, with EXECUTOR_DATA_DIR and optional EXECUTOR_DB_PATH.
• Cloudflare host: D1, with optional R2 blob storage.
• Hosted Executor cloud app: Postgres via DATABASE_URL / Hyperdrive.

For Central, use the local CLI daemon shape:

EXECUTOR_DATA_DIR=/Users/Shared/joelclaw/data/executor

Expected state files after a successful start:

/Users/Shared/joelclaw/data/executor/data.db
/Users/Shared/joelclaw/data/executor/data.db-wal
/Users/Shared/joelclaw/data/executor/data.db-shm
/Users/Shared/joelclaw/data/executor/server-control/auth.json

Do not move Central Executor to Central Postgres unless Executor exposes and documents a supported local Postgres backend. The hosted app using Postgres is not proof that the local CLI daemon should.

Do not put Executor state on three-body or a NAS mount. NAS storage can disappear, block boot, or add latency. Executor belongs on local Flagg disk with explicit backups later.

LAN And Tailnet Exposure

Executor is intentionally available to joelclaw machines over LAN and tailnet. The daemon binds 0.0.0.0:4788; do not "repair" it back to localhost unless Joel explicitly reverses the service-access decision.

For humans, prefer the easy dashboard proxy on 4789. It runs as joelclaw, reads the local bearer token server-side, injects Authorization: Bearer ... only on upstream requests to 127.0.0.1:4788, and allows only loopback, Flagg LAN 192.168.1.0/24, Tailscale IPv4 100.64.0.0/10, and Tailscale IPv6 fd7a:115c:a1e0::/48.

Easy dashboard URLs:

http://127.0.0.1:4789/
http://192.168.1.10:4789/
http://100.99.76.47:4789/
http://joels-mac-studio.tail7af24.ts.net:4789/
http://100.127.252.116:4789/
http://flagg.tail7af24.ts.net:4789/

The bearer token is still the gate for /api, /mcp, MCP approval/OAuth await paths, and agent access. Executor mints/loads it from:

/Users/Shared/joelclaw/data/executor/server-control/auth.json

Never print that file or put the token in plists, process args, docs, chat, or shell history. For agent configuration, use a redacted instruction or have the operator read the token locally.

Raw daemon URLs:

http://127.0.0.1:4788/
http://192.168.1.10:4788/
http://100.99.76.47:4788/
http://joels-mac-studio.tail7af24.ts.net:4788/
http://100.127.252.116:4788/
http://flagg.tail7af24.ts.net:4788/

Resolve current dashboard endpoints from the installed Executor configuration and verified network identity. Verify the exact URL returns the expected page before sharing it. Historical IPs and hostnames above are diagnostic history, not routing defaults.

Do not use Tailscale Serve for Executor without preserving the existing Serve config for /, /notes, Vite asset paths, and the Convex TCP forwards. Direct ports 4788 and 4789 are the current contract.

Install And Apply

Run from the Central repo:

cd /Users/joel/Code/joelhooks/joelclaw-central
scripts/install-executor-launchdaemon.sh --dry-run
scripts/check-contract.sh
scripts/check-contract.sh --runtime
pnpm run brain:check

Apply requires root because it installs a system LaunchDaemon:

cd /Users/joel/Code/joelhooks/joelclaw-central
sudo scripts/apply-executor-slice.sh

For Joel-friendly dashboard access on Flagg, use:

cd /Users/joel/Code/joelhooks/joelclaw-central
scripts/open-executor-dashboard.sh

That helper installs the dashboard LaunchDaemon with sudo if needed, checks http://joels-mac-studio.tail7af24.ts.net:4789/, then opens it.

If the shell does not have passwordless sudo, do not fake success. Report the actual file and dry-run results, including failures or checks not run, then identify the exact privileged step that remains.

Do not run:

executor service install

The service belongs to the Central repo. Executor's own service installer bypasses the Central boot contract and can hide state/log paths.

Health Checks

After apply:

launchctl print system/com.joelclaw.central.executor
launchctl print system/com.joelclaw.central.executor-dashboard
curl -fsS -m 5 http://127.0.0.1:4788/ >/dev/null
curl -fsS -m 5 http://127.0.0.1:4789/ >/dev/null
curl --noproxy '*' -fsS -m 5 http://192.168.1.10:4788/ >/dev/null
curl --noproxy '*' -fsS -m 5 http://192.168.1.10:4789/ >/dev/null
curl --noproxy '*' -fsS -m 5 http://100.99.76.47:4788/ >/dev/null
curl --noproxy '*' -fsS -m 5 http://100.99.76.47:4789/ >/dev/null
curl --noproxy '*' -fsS -m 5 http://joels-mac-studio.tail7af24.ts.net:4788/ >/dev/null
curl --noproxy '*' -fsS -m 5 http://joels-mac-studio.tail7af24.ts.net:4789/ >/dev/null
scripts/verify-executor-runtime.sh

Useful narrow checks:

pgrep -fl "executor.*daemon run"
lsof -nP -iTCP:4788 -sTCP:LISTEN
lsof -nP -iTCP:4789 -sTCP:LISTEN
test -f /Users/Shared/joelclaw/data/executor/data.db
test -f /Users/Shared/joelclaw/data/executor/server-control/auth.json
tail -n 120 /Users/Shared/joelclaw/logs/executor/launchd.err.log
tail -n 120 /Users/Shared/joelclaw/logs/executor/launchd.out.log
tail -n 120 /Users/Shared/joelclaw/logs/executor-dashboard/launchd.err.log
tail -n 120 /Users/Shared/joelclaw/logs/executor-dashboard/launchd.out.log

Version check:

/Users/Shared/joelclaw/opt/executor/1.5.12/bin/executor --version

Status check:

EXECUTOR_DATA_DIR=/Users/Shared/joelclaw/data/executor \
  /Users/Shared/joelclaw/opt/executor/1.5.12/bin/executor daemon status

Safety Rules

• Keep Executor available only on Joel-controlled LAN/tailnet paths. Do not expose it publicly without a separate auth/gateway decision.
• Do not pass bearer tokens or auth secrets in process args. Process args are visible through ps.
• Do not print, paste, or URL-encode the dashboard bearer token. Use the 4789 proxy for browser access instead.
• Do not print server-control/auth.json.
• Do not delete data.db, WAL files, or server-control/ without an explicit backup and recovery plan.
• Do not replace the pinned version casually. Check upstream release notes/source first, then update wrapper, installer, docs, and contract checks together.
• Do not run long log tails without bounds. Use tail -n.
• Treat Executor as an execution surface. Be suspicious of public exposure, broad filesystem scopes, and ambient credentials.

Source Checks

Primary upstream:

• https://github.com/RhysSullivan/executor
• https://github.com/RhysSullivan/executor/blob/main/docs/self-hosting/guide.mdx

Before changing version or storage assumptions, verify current upstream behavior from source or release docs. Executor changed quickly around June 2026; do not rely on stale package memory.

Local source inspection pattern:

tmpdir="$(mktemp -d)"
git clone --depth 1 https://github.com/RhysSullivan/executor "$tmpdir/executor"
rg -n "EXECUTOR_DATA_DIR|EXECUTOR_DB_PATH|DATABASE_URL|data.db|libsql|sqlite|D1|Hyperdrive" "$tmpdir/executor"

When using web or GitHub sources in an answer, cite the upstream URLs and distinguish source-grounded facts from local Central decisions.