# Quickstart

Five minutes from install to a thread advancing.

> **On the hosted beta (app.yothere.ai)?** Follow
> [`docs/BETA-GUIDE.md`](docs/BETA-GUIDE.md) instead. This page is the self-host /
> local path.

## What you need first

- A Mac or a Linux box (Windows: use WSL2).
- Python 3.11, 3.12 or 3.13 (not 3.14).
- `pipx` (`brew install pipx` on macOS).
- For real work: your own Claude Code (`claude` on PATH) or Codex CLI (on a ChatGPT
  subscription). The bundled demo below needs neither.

## 1. Install

```bash
pipx install yothere
```

## 90-second demo (no key, no account)

`yothere init` sets up `~/.yothere` (override with `YOTHERE_HOME`; an existing `~/.relay`
is reused), detects any brain you already have, and wires the bundled zero-key demo brain
if you have none. It is idempotent and never overwrites existing config. (`YOTHERE_*` is
the canonical env namespace; legacy `RELAY_*` names still resolve.)

```bash
yothere init          # one-time setup + a status block with your next commands
yothere init --demo   # watch a live fleet end to end (~30s, zero keys)
yothere board --open  # the board it just filled
```

`--demo` starts a bundled Brain Protocol v1 brain on localhost, spawns one thread
("Demo: competitive scan"), and advances it through the real runner -> worker -> brain
path: it streams progress, goes **blocked** asking for your eyes, gets replied to the way
you would (`yothere reply <id> "ship it"`), and finishes **done** with a result summary.
Everything stays under `YOTHERE_HOME`; Ctrl-C is safe.

## 2. Run against the bundled reference brain

The `echo_brain` is the smallest valid Brain-Protocol implementation (~60 lines) and the
conformance fixture. Use it to prove the loop before wiring a real brain.

```bash
# terminal 1: the reference brain
python -m yothere.voicecall.echo_brain --port 9999

# terminal 2: point yothere at it and drive a thread
export YOTHERE_REMOTE_BRAIN_URL=ws://127.0.0.1:9999
export YOTHERE_THREAD_HARNESS=remote
yothere spawn "summarize the state of agentic commerce"
python -m yothere.runner once          # advance one tick
yothere board --open                    # glance at the fleet
```

## 3. Point at a real agent

Run threads on a local coding agent instead of the reference brain. Use whichever one you
already pay for.

```bash
export YOTHERE_THREAD_HARNESS=claude    # needs the `claude` CLI on PATH
# ...or, on a ChatGPT subscription:
export YOTHERE_THREAD_HARNESS=codex     # needs the Codex CLI; `yothere doctor` finds it

export YOTHERE_WORK_DIR=~/yothere-scratch   # where the agent runs (see the warning)
yothere spawn "draft the Q3 update"
python -m yothere.runner loop           # always-on advance engine
```

> **Read this before you run it.** A local harness runs your agent at full capability
> inside `YOTHERE_WORK_DIR`, without per-action prompts: `claude -p --permission-mode
> bypassPermissions`, or `codex exec -s danger-full-access`. Point `YOTHERE_WORK_DIR` at
> a scratch or throwaway directory, never at a repo you would mind an agent editing. What
> yothere does contain is outward sends: a send-gate stops an unattended turn at `blocked`
> before it emails, posts or pushes, and waits for your approval. `git push` and `gh` can
> never be granted by any approval. The gate is a guardrail, not a sandbox (it inspects
> shell and tool calls, so reads and outbound GET requests are not contained), and the
> brain still owns its own safety. Full model in [`SECURITY.md`](SECURITY.md).

Either set `YOTHERE_REMOTE_BRAIN_URL` (+ `YOTHERE_REMOTE_BRAIN_TOKEN`) to a `wss://`
endpoint, or register named brains in `~/.yothere/brains.yaml` and select one with
`YOTHERE_BRAIN`. See [`docs/configuration.md`](docs/configuration.md).

## 4. Code work in a repo you already have

Register a repo as a workspace, then bind a thread to it. The thread's turns run in their
own git worktree (`~/.yothere/worktrees/<workspace>/<thread>`), on their own branch, so
your working tree is never touched and two code threads never collide.

```bash
yothere workspace add site ~/code/yothere-site   # register a repo you already have
yothere workspace list                            # what is registered
yothere spawn --repo site "fix the layout shift on the pricing page"
```

- **yothere never clones.** A workspace is a repo already on this machine, and yothere
  holds no git credential.
- **No approval can unlock a push.** `git push` and `gh` are in a never-grant list, so
  there is no button that opens a push, a PR or a merge. The agent works on a branch,
  commits, and hands the work back for you to read. It is a rule in the gate, not a
  sandbox: `YOTHERE_WORKER_SEND_POLICY=open` disables the gate, and a GitHub MCP server
  you install yourself can carry a publish tool the gate does not read as a send.
- The worktree is isolation from other threads, not a sandbox. `YOTHERE_WORK_DIR` still
  applies to unbound threads. Full model in [`SECURITY.md`](SECURITY.md).

## 5. Implement your own brain

Implement [`docs/brain-protocol-v1.md`](docs/brain-protocol-v1.md) (`hello`,
`streamSubscribe`, `prompt`, streaming `delta` frames). Add `progress` / `status` / `cost`
to light up the cockpit fully. Read `echo_brain.py` for the shape.

## Everyday commands

```bash
yothere spawn "<task>"        # create a thread (or: yothere preset <key> <arg>)
yothere spawn --repo <name> "<task>"   # ...bound to a registered repo (own worktree)
yothere workspace add <name> <path>    # register a local git repo (list | rm)
yothere list                  # live threads + state
yothere show <id>             # status, plan, transcript
yothere reply <id> "<text>"   # answer a blocked thread -> it re-advances
yothere focus <id>            # pin the focus thread (never auto-interrupted)
yothere board --open          # the glance board
yothere note "<text>"         # capture a reminder (no thread)
```

There is no scheduler. A hail runs once, immediately (see the
[roadmap](https://yothere.ai/roadmap/)).

## Hosted beta (BYO compute)

On [app.yothere.ai](https://app.yothere.ai) the control plane holds auth and state while
your own laptop runs the agent. Nothing advances while your machine is asleep; dispatched
tasks queue and drain the moment it reconnects. Pairing runs a browser device flow, and
ends with an always-on worker so dispatched tasks and voice calls reach it:

```bash
yothere login                 # prints a short pairing code (XXXX-XXXX) plus a link to
                              # https://app.yothere.ai/activate. Open it in the browser
                              # where you are already logged in, confirm which machine is
                              # asking, and pick its permission tier (read-only by default,
                              # up to full, which ticks a bypass-consent checkbox). The CLI
                              # polls and saves the credential. No token is pasted.
yothere service               # foreground once: it prints the bypass-permissions consent
                              # and blocks until you acknowledge it. Read it.
yothere service install       # then make it an always-on leaser that survives reboots
```

Raise or lower a machine's tier any time in Settings, Machines.

On a self-host, headless or SSH-only box with no browser, use the legacy token path
instead: mint a single-use token in the cockpit's "Pair a machine" panel and paste it.

```bash
yothere login --url https://app.yothere.ai --token <paste>
```

Full walkthrough: [`docs/BETA-GUIDE.md`](docs/BETA-GUIDE.md).
