Modes

One installer. After install, choose where the Yoke core and its database live.

Local

Private on your machine. No signup. One human, as many agents as you want. On macOS, local mode requires macOS 26.0 or newer for its pinned embedded PostgreSQL build, on both Apple Silicon and Intel. Older systems refuse before download or initialization; upgrade macOS or connect to a remote core. See installation requirements.

A local install is reachable here only: the engine and its workbench answer on this machine alone, so no other computer can connect to it. yoke status says local: reachable here only. To work from more than one computer, or with a team, pick Host a server here (self-hosted) or upyoke.com instead, then move this universe across with export/import.

• Wizard: pick This machine (reachable here only; it asks your name: you become the universe's first admin), or run yoke init --local --admin-name "Your Name"
• Data under ~/.yoke/
• The machine relay is installed here too, so the workbench sees which harnesses this machine can start, reports session liveness, and can launch and resume sessions. It runs your installed Yoke and needs no account or API token. macOS uses a LaunchAgent; Linux uses a systemd user service that stops at logout without linger. See Linux relay supervision.
• Open the workbench with yoke ui up (detached; yoke ui reports it, yoke ui down stops it)
• Billing and Team seats do not apply (Cloud-only platform features)

Init preserves an existing active connection. Use yoke init --local --activate to select local explicitly; see connection repair.

Portable: yoke universe export dumps the universe into the machine Yoke home exports folder (normally ~/.yoke/exports/). Pass --out PATH to choose a file or folder. Import the archive later into self-hosted or another local machine.

Local browser function calls to POST /api/functions/call require an object in payload, just like the self-hosted workbench. Omit it or send {} for an empty payload. null, lists (including key/value pairs), strings, numbers, and booleans receive HTTP 422 envelope_invalid with recovery text before dispatch.

Yoke Cloud

Hosted core at upyoke.com. Collaborate from the web dashboard.

• Wizard: pick upyoke.com (private beta; it requires a beta code)
• Sign-in, beta-code redemption, org founding, and machine approval happen in the connect step
• Private beta: seats and tenant attached to the code; bring your own workers and model credentials
• Billing and the seat section at the top of Team are platform-managed

Hosted cores serve through the same trusted-proxy boundary as self-hosted ones: only transport peers listed in YOKE_API_TRUSTED_PROXIES (explicit IPs/CIDRs, never *) may supply X-Forwarded-Host, X-Forwarded-Proto, and X-Forwarded-For. The hosted platform declares its relay peers there, so origin-checked routes compare Origin against the public host rather than the engine's upstream address.

Self-hosted

Run Yoke core and Postgres on your own server.

Open its workbench with yoke ui up on a connected machine: company sign-in opens the server URL; without OIDC, the API token gets a single-use browser sign-in link valid for two minutes. Rerun the command if the link expires. Sign-in links are never printed, including in JSON. If a browser cannot open or an agent runs the command, run yoke ui up from your own terminal on a machine with a display.

• Wizard on the host: pick Host a server here to preview the loopback URL, bundle directory, port, Docker requirement, and networking responsibility before any write. Start asks your name, creates/starts the Compose bundle so first boot makes you the first admin, captures the admin token, waits until the server answers /v1/health, and activates the owner-only local connection. Rerun it on a host whose bundle already exists to restart that bundle and reconnect with its first-boot token. The bundle lives in ~/.yoke/yoke-server, or YOKE_MACHINE_HOME/yoke-server when set, outside projects.
• Wizard on another machine: pick A team server and enter its reachable URL first. Company sign-in (OIDC), when configured, opens the workbench with a one-time code so you approve your own machine. Otherwise provide a pasted API token or token-file path; your own next machine can instead run yoke connect URL and approve its code from a machine you already connected. The guided host screen teaches the handoff without configuring VPN/tailnet, LAN, port-forwarding, or TLS for you. When the URL cannot be reached, the error names the failure (server_name_unresolved, server_timed_out, server_refused, server_https_failed or server_not_yoke); run yoke status on the server machine to see what it serves. A local install answers local: reachable here only there.
• Manual/operator path: yoke self-host init --admin-name "Your Name" --start writes and starts the same Compose bundle through the private host secret handoff. Restart with yoke self-host init --dir PATH --protect-existing --start; docs/self-host.md remains the full reference.
• The server serves the workbench at its own URL. People sign in with company sign-in (OIDC) and work with full read and write as their own actor; see Browser Sign-In
• Billing and Team seats do not apply (Cloud-only platform features)

yoke self-host init keeps loopback-only by default; add --listen ADDRESS to publish on a LAN or Tailscale IP (or 0.0.0.0 for all IPv4 interfaces). Teammates use the printed yoke connect http://ADDRESS:PORT command with a reachable private address. Private HTTP allows 10/8, 172.16/12, 192.168/16, 100.64/10, fd00::/8 and *.ts.net. Each connect warns that the machine token travels unencrypted: safe on Tailscale or a VPN; use TLS on a shared LAN. Public HTTP is refused; use HTTPS.

yoke self-host init warns when YOKE_API_PUBLISH in the bundle's .env publishes beyond loopback. Docker bypasses ufw/firewalld for published ports; bind to 127.0.0.1 behind a TLS reverse proxy, or restrict access upstream. The warning never blocks setup or startup. Declare the TLS proxy's transport IPs/CIDRs in .env as YOKE_API_TRUSTED_PROXIES, then restart with yoke self-host init --dir PATH --protect-existing --start. Preserve Host and forward X-Forwarded-Proto and X-Forwarded-For; undeclared peers are ignored.

Source available

Yoke is Fair Source (FSL-1.1-ALv2). Use, modify, and self-host; the license converts to Apache 2.0 after its fixed window. Public source: github.com/upyoke/yoke.

The wizard's Edit Yoke source row accepts an existing checkout or any public fork. That checkout powers the local CLI and harness, and powers the in-process engine in Local mode. If the same machine is also the guided self-host, Yoke uses its existing checkout build/start path for the server image. Existing remote self-hosted and Cloud servers are not redeployed by this choice; they continue running their deployed build.

Switching later

Universes are portable between modes via export/import. The client reconnects; you do not re-author strategy or backlog from scratch.

Server liveness, cached readiness and authenticated identity have separate meanings; see server health readiness.