Configuration

yothere reads all of its configuration from environment variables through yothere.config.settings. Nothing is required to start: the defaults give a working setup. This page lists the variables that matter, the brains.yaml registry, the two run modes, and how the legacy RELAY_* names still resolve. For the setup flow, see Onboarding.

How configuration resolves

Configuration comes from two layers. A service wrapper first sources $YOTHERE_HOME/yothere.env (a mode-600 KEY=value file) into the environment, then the process environment applies on top. settings reads env at import time, and every writable path roots at YOTHERE_HOME (default ~/.yothere, falling back to an existing ~/.relay).

Core environment variables

The derived roots YOTHERE_DATA_DIR, YOTHERE_STATE_DIR, YOTHERE_LOG_DIR, YOTHERE_THREADS_DIR, and YOTHERE_VAULT_DIR default to subdirectories of YOTHERE_HOME and rarely need overriding.

Agent backends

A worker turn runs on the coding-agent subscription you already have. Two local harnesses ship: claude (the Claude Code CLI) and codex (the OpenAI Codex CLI). They are peers, not a main mode and a lesser one: same containment, same approve-send grant, same resume, same caps. A remote harness reaches anything else that speaks the Brain Protocol.

Code workspaces

The git repos yothere may work in are registered with yothere workspace add <name> <path>, not configured by env. The registry is workspaces.json next to your threads dir, and it holds paths only: yothere never clones a repo and holds no git credential.

A thread bound to a workspace ignores YOTHERE_WORK_DIR and runs in its own git worktree under $YOTHERE_HOME/worktrees/, on its own branch. Unbound threads keep running in YOTHERE_WORK_DIR exactly as before. See the CLI reference.

The brains.yaml file

A brain is whatever does the work; yothere drives it over the Brain Protocol. $YOTHERE_HOME/brains.yaml maps names to connection descriptors:

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

A thread targets a brain by its brain meta key; otherwise YOTHERE_BRAIN, then the file’s default, then local-claude. A remote (non-loopback) endpoint must require a token and should be wss://. Reference the token with token_env: so the secret is not in the file, and treat brains.yaml like an SSH key (do not commit it). yothere init seeds this file only when it does not already exist.

Codex harness

Codex auth is a one-time login into the CODEX_HOME that yothere owns, not an API key and not your personal ~/.codex (yothere never reads or writes that):

CODEX_HOME=~/.yothere/state/codex-home codex login

yothere doctor warns when that home has no auth.json and prints the exact command for your paths.

Parallelism

Running several agent turns at once is the point of the product, and both engines ship with the same shape: a pool of work turns, plus a separate pool for typed questions, so a reply never queues behind long work.

Cost caps

The runner and the hosted planner both stop advancing turns once a cap is reached. A capped thread comes back to the Inbox as an answerable card, so you can continue it, raise its cap, or stop it.

Voice

Voice is a hosted service. You configure nothing and you bring no key: click Connect in the cockpit and the control plane mints a short-lived per-call token for the session. There is no key to set, no phone number, and nothing to install.

The one exception is the loopback dev path, yothere voice --local, which boots a media host on 127.0.0.1:8767.

Output language

The agent’s output language is a per-workspace setting, not an environment variable. Choose English or Español (Latinoamérica) in the cockpit at /settings, and the agent plans, asks, reports, and speaks in it. English is the default for every account, and /settings is the only place the choice is made: there is no auto-detection and no Accept-Language sniffing.

Prose follows your language; the machine contract underneath (thread states, the ask kinds a daemon reads) stays English by design, so a Spanish thread still rings you exactly like an English one.

Run modes

YOTHERE_AUTH_MODE selects the deployment mode.

Signup is open self-serve. In hosted mode an operator can also mint invite codes from the CLI, for example to pre-provision a specific account with a set budget. Each redemption at /signup creates exactly one account, stamped with the daily cost cap you set:

yothere invite create --uses 1 --budget 5 --email [email protected]

Per-tenant homes live at ~/.yothere-<tenant> under YOTHERE_TENANTS_ROOT (default: the parent of YOTHERE_HOME). This is an implementation detail of hosted mode, not something you set on your own machine.

Legacy RELAY_ aliases

Every YOTHERE_* variable also accepts its RELAY_* sibling. An env shim mirrors both prefixes at package import, and again when parsing an env file, so a config keyed either way resolves regardless of which name a reader asks for. When both names are present, the reader’s requested name wins (the shim only fills a name that is unset and never overwrites an explicit value).

# these are equivalent
export YOTHERE_WORK_DIR=~/code/my-project
export RELAY_WORK_DIR=~/code/my-project

New configs should use the YOTHERE_* names. The legacy RELAY_* names stay supported for at least one release.