yothere

Agent onboarding

A copy-paste runbook for an AI agent setting yothere up on a machine.

Beta · access required

yothere is in invite-only beta. The commands below work once you have access.Request access and we'll get you set up.

Terse, imperative, copy-paste. Run the blocks top to bottom. Every command below is verified against the installed yothere 1.5.2 package. For prose explanations, follow the cross-links to the human docs.

Who this is for

You are an AI agent (or an operator scripting one) setting up yothere on a fresh machine so a fleet of headless threads can run and page a human only when they need judgment. yothere is the interface and attention router; the actual work is done by a brain (Claude Code, or any harness that speaks the Brain Protocol).

Prerequisites

  • Python 3.11 or newer on PATH (python3 --version).
  • macOS or Linux. Windows via WSL2 (takes the Linux/systemd path).
  • Outbound network for pip.
  • A brain to do the work: either a local claude CLI on PATH, or a reachable Brain Protocol endpoint (ws:// or wss://). The demo needs neither.

1. Install

Install into a dedicated venv under the yothere home so the always-on service has a stable, non-ephemeral interpreter.

python3 -m venv ~/.yothere/venv
~/.yothere/venv/bin/pip install yothere

Do not install with uvx or pipx run: those interpreters live in caches that get garbage-collected, and the service refuses to template units against them.

2. Smoke test

Zero-key end-to-end check. Spawns one thread and drives it through the real runner to completion (spawn to work to blocked to reply to done) in about 30 seconds, no API keys.

~/.yothere/venv/bin/yothere init --demo

Expect it to stream progress, go blocked asking for your eyes, get replied to, and finish done with a result summary on the board. If the fleet already has running threads it refuses (so it does not advance real work); run it in a scratch home instead:

YOTHERE_HOME=$(mktemp -d) ~/.yothere/venv/bin/yothere init --demo

3. Connect a brain

Real init. Creates the ~/.yothere layout (threads/ data/ state/ logs/), detects any brain already present, and seeds a commented brains.yaml with a bundled demo brain when none exists. Idempotent and never overwrites existing config.

~/.yothere/venv/bin/yothere init

A local claude CLI on PATH is auto-detected. Otherwise edit ~/.yothere/brains.yaml and add either a local-claude entry or a remote entry:

default: local-claude
brains:
  local-claude: {harness: claude}
  my-brain:     {harness: remote, url: "wss://host/brain", token_env: "MY_BRAIN_TOKEN"}

See Configuration for every brain option.

4. Configure

Set the two load-bearing env vars in ~/.yothere/relay.env (or your shell). Lead with the YOTHERE_* names; the legacy RELAY_* siblings still resolve.

# The directory workers run in and are scoped to. Use a normal project dir.
export YOTHERE_WORK_DIR="$HOME/code/your-project"
# How you get paged when a thread needs you: command | telegram | none.
export YOTHERE_NOTIFIER=command
Heads up YOTHERE_WORK_DIR must NOT be under ~/Documents or ~/Desktop. macOS TCC blocks a launchd worker from reading those, so a worker there crash-loops on first file access. Onboarding refuses them up front.

Full env reference: Configuration.

5. Run onboarding steps

The onboarding registry is the one source of truth for “is this install set up?”. Check state, then apply each step.

python -m yothere.onboarding status

Steps, in order: brain, workdir, consent, notifier, service, mcp, voice, first_thread. Apply each with apply <step>. Some steps take --args (JSON); the steps that touch the system or store consent (consent, service, mcp, voice) are not auto-safe, so pass --yes in a non-interactive shell.

python -m yothere.onboarding apply brain
python -m yothere.onboarding apply workdir  --args '{"path":"'"$HOME"'/code/your-project"}'
python -m yothere.onboarding apply consent  --yes
python -m yothere.onboarding apply notifier --args '{"kind":"command","target":"notify-send yothere"}'
python -m yothere.onboarding apply service  --yes
python -m yothere.onboarding apply mcp      --yes
# voice is optional (needs a Gemini key):
python -m yothere.onboarding apply voice    --args '{"key":"<GEMINI_API_KEY>"}' --yes
python -m yothere.onboarding apply first_thread --args '{"task":"ship the pricing page fix"}'
Heads up The consent step records explicit acknowledgement that the local-Claude harness runs unattended worker turns with claude -p --permission-mode bypassPermissions, scoped to YOTHERE_WORK_DIR: inside a worker turn the brain may read and write files and run commands without per-action prompts. A relay-owned send-gate denies outward sends in headless turns, and blocked threads stop and wait for your reply. Only proceed if you accept unattended tool use in that directory. See Onboarding.

6. Install the service

Install the always-on units (launchd on macOS, systemd user units on Linux): the runner and its watchdog. Preview first with --dry-run, which prints every file and command without touching the system.

python -m yothere.service install --dry-run
python -m yothere.service install

Add --cockpit to also install the cockpit/voice server (needed for the /overview board and the /healthz probe below; requires the voice extra). Verify with python -m yothere.service status. Detail: Self-hosting.

7. Spawn the first thread

yothere spawn "ship the pricing page fix"

Spawning is pure file I/O and safe in-session. The installed runner advances it; without the service, advance by hand with python -m yothere.runner loop.

8. Verify

yothere list                                   # live threads + state
yothere board                                  # build the standalone fleet board
curl -s http://127.0.0.1:8767/healthz          # cockpit/voice server health (port 8767)

The /healthz probe answers only once the cockpit/voice server is running (installed with --cockpit in step 6). If it is not installed, open the board file printed by yothere board, or the /overview page when the server is up. A blocked thread means the attention router is doing its job: answer it with yothere reply <id> "<text>".

Machine-readable index

A compact, machine-readable index of the whole site and the setup command block lives at /llms.txt. Fetch it to orient before crawling the docs:

curl -s https://yothere.ai/llms.txt