Install

curl -fsSL https://upyoke.com/install | sh
yoke setup
yoke status

Prerequisites: a shell, curl, and uv (the installer can install uv with consent). Yoke supports Python 3.11–3.14. When no supported interpreter is available, uv downloads a managed one automatically for the installer and yoke update, without changing your system Python. Native Windows is unsupported; WSL follows the Linux path. Run installation, onboarding and harness CLIs inside the WSL Linux filesystem with systemd enabled. To open a URL in the Windows browser, Yoke tries wslview, then explorer.exe if Python's browser opener fails. Install wslu or enable Windows interop/PATH when both are unavailable. Verify the local UI through Windows localhost forwarding before changing WSL networking modes. Install and onboard Apply disable WSL2 idle shutdown through the Windows user profile .wslconfig (WSL 2.5.4 or newer). Older WSL or unavailable Windows interop warns without blocking completion; run wsl --update from Windows and retry yoke wsl setup. Preview does not write WSL configuration. Follow the printed wsl --shutdown restart step when setup changes it; afterward terminals can close while the relay and background work continue. After a deliberate distro shutdown, run yoke init --local to restart its Postgres authority. See Yoke on Windows (WSL) for filesystem, systemd, and agent setup.

Linux requires glibc (for example Ubuntu, Debian, or Fedora); musl hosts such as Alpine are refused before installation. Amazon Linux 2 on arm64 is unsupported: its glibc is too old for the aarch64 psycopg wheels.

If Python's automatic download fails or downloads are disabled, the installer reports supported_python_unavailable. Check network access and uv's Python download settings, or run uv python install ">=3.11,<3.15", then rerun the installer or yoke update.

Yoke creates ~/.yoke and missing private state and secret directories with mode 0700, including when the shell uses umask 002. Existing directories keep their permissions. If the machine-config lock refuses a group- or world-writable ~/.yoke, run chmod 700 ~/.yoke and retry. For a custom machine home, use the exact directory and chmod command named in the refusal.

Onboard wizard

yoke setup is a full-screen wizard:

1. Install / PATH — confirm the CLI
2. Account — where Yoke lives (this machine / team server / upyoke.com)
3. GitHub — optional App connect for product GitHub commands
4. Project — create, clone, import, or bind a checkout. A clone is

fetched here, not at Apply, so you see what the repository holds — and decide what happens to any Yoke files it already carries — first

1. Review — preview persistent writes, then apply

Anything the wizard already finds — a checkout carrying Yoke files, a repository that already has a project, a checkout already mapped on this machine — is announced before you answer anything, and connecting to what exists is the default. The mouse scrolls and clicks normally; on any screen showing a URL or a one-time code the footer names a copy key (^y) and an open-in-browser key (^o) instead of a native drag-select.

For A team server, enter its URL first. When company sign-in is configured, Yoke opens the workbench with a one-time machine code; sign in and approve your own machine. Otherwise paste an API token or select its file. The same flow is available with yoke connect https://<server>; servers without company sign-in use --token-stdin or --token-file PATH.

Flags: --yes for non-interactive apply; --local or --connect URL to skip the destination picker.

After onboard

The installer runs uv tool update-shell; uv chooses the shell configuration to update, including bash and fish. If uv cannot determine the current shell (for example, in a noninteractive shell without SHELL), the installer completes its checks using the installed executable's absolute path and prints Add Yoke to PATH: export PATH=... with the exact bin directory. Run that command in your shell; add the same directory to your shell's startup PATH to keep it available in future terminals. Other shell-update failures stop the installer with uv_shell_update_failed. Open a new terminal. If you chose machine-only setup, the finish screen lists the projects your account can access and commands to file and browse work from any folder, plus your hosted dashboard link (or the team server's own URL, where yoke ui up opens its workbench). Run yoke setup when you want to prepare a project's code on this machine. Once that project is wired, open Claude Code, Codex, or Cursor in its folder and run /yoke onboard.

yoke status          # machine, env, credentials, checkouts
yoke ui up           # local daemon, or the connected self-host workbench
# or open the Cloud dashboard after sign-in

On a team server, yoke ui up opens company sign-in when configured. Otherwise it uses the connection's API token to open a single-use browser sign-in link for that actor. The link expires in two minutes; rerun the command if needed.

Upgrade later with yoke update — it reruns the official installer with onboarding disabled, honors this machine's already-configured distribution origin and channel, and reports the verified old and new version (or that you're already current). The installer saves its origin and channel in settings.distribution in ~/.yoke/config.json, so a fresh shell uses the same distribution. An install without that record refuses updates; explicitly select one with yoke config distribution set --origin URL --channel NAME before retrying. yoke update --channel NAME selects another channel at the recorded origin; a successful reinstall saves that channel for later updates. The installer itself repairs the git credential helper a reinstall wipes from site-packages, as the last step of every successful run — so re-running the curl installer directly still resolves the same channel version for every Yoke product package and still repairs the helper, just without the version-change report.

yoke update and yoke self-host upgrade refuse to replace an active Yoke source-checkout install with packaged releases. Update that checkout with git; for a server built from it, rebuild through yoke core upgrade --from-checkout /path/to/yoke --build.

The first command you run after an upgrade brings the rest of the install up to the new engine. A machine-local universe has its schema converged before the command is served — the same step a hosted container runs on boot. Additive foreign keys match the live environments.id type so a universe still on text keys reaches the ordered history that converts them. Every control-plane connection declares a bounded idle_in_transaction_session_timeout and TCP keepalives as libpq startup options, so an abandoned transaction releases its locks without an operator and a half-dead forward is noticed rather than waited on. That is a property of the connection, which is what makes it hold whatever role the client authenticates as — a role default is scoped to one (role, database) pair, so a client connecting as an admin role inherits that role's value rather than the serving role's. The convergence additionally records the same bound as the role's database default, for sessions Yoke did not open; that write is best-effort, so a role that cannot alter its own defaults — or a second boot racing on the same catalog row — degrades with an application_role_default_not_persisted diagnostic on stderr instead of refusing every read. A project checkout whose operating layer predates the new engine is named once, with the yoke project install <checkout> that refreshes it. Run that when it appears; otherwise the checkout keeps teaching the previous release.

Project-only install

If the project already exists in the universe and you only need the repo operating layer:

yoke project install ~/path/to/checkout

That materializes skills, agents, hooks, and .yoke/docs from the engine's public docs corpus.

The run finishes the job rather than leaving you a commit to push. It fetches the branch's remote first and fast-forwards when the checkout is simply behind, so the layer is generated against current upstream; it commits the paths it owns; and it pushes that commit. If the remote advanced while the run was writing, it moves onto the new revision and regenerates the layer there — never a merge, which would keep whichever obsolete generated content the older side happened to carry.

Where the branch does not accept a direct push, the same commit is pushed to a yoke-install/<sha> branch and proposed as a pull request. Where the push cannot land at all, the report says publication_pending and names the commit plus the command that finishes it — and the command exits 3 rather than reporting a clean install the remote never saw.

Two refusals are deliberate. A default branch carrying commits of your own that the remote lacks is reported instead of pushed, because publishing the layer is not permission to publish your work-in-progress — and a commit merely titled like an install counts as yours unless its changes stay inside what the install writes. Files it shares with you rather than owns are on your side of that line: it merges its hook entries into your .claude/settings.json, appends one line to your .gitignore, and writes into the file-line policy config, so it cannot tell its content there from yours. A commit it did not just make that touches one of those is reported — never pushed, and never rewritten while reconciling with the remote. And a checkout with no remote is a local-only project: publication is skipped, not failed, as it is for --no-commit. Pass --no-publish to commit without pushing.

An unreachable remote does not stop the install, which is the one place it differs from starting other work. Creating a worktree refuses an unverifiable remote, because new work would have no current revision to start from; installing writes a local layer, so an offline machine still gets the thing it asked for. The run records why it could not read the remote and publication then reports publication_pending — you are never told the remote has a layer it never received.

Uninstall

yoke uninstall

On a machine holding a local universe or a self-host server, the first output warns that uninstall deletes its only copy of the universe data. Choose back up first to run yoke universe export for each owned universe, or uninstall without backing up. There is no automatic backup. Exports land in your current directory; run the command outside the machine home. A failed export stops removal and names the recovery. Hosted-only clients see no data warning.

Next, the command lists registered checkouts with a Yoke install manifest. Choose all, none, or a selection to also run yoke project uninstall on. A Git checkout must be on the project's configured default branch before its layer is removed. An unset default branch refuses until it is configured. It then removes the relay and stops its workers, removes the selected project layers, disconnects Yoke's GitHub credentials and checkout helpers, stops the local UI and embedded Postgres, tears down local self-host stacks including their universe volumes, and deletes the machine home (~/.yoke or YOKE_MACHINE_HOME). No further confirmation is required. Finally a detached worker removes the CLI with uv tool uninstall yoke-cli after the uninstall process exits. Its result log is printed by the command.

Each step reports done, skipped with a reason, or failed with a named recovery. Independent cleanup continues after a failure; the machine home and CLI stay available when cleanup needs recovery. Fix the reported problem and retry. Source-checkout CLI installs refuse; retire those through your source-dev workflow.

For unattended removal, make the same choices explicitly:

yoke uninstall --projects all --yes                 # hosted-only client
yoke uninstall --backup --projects none --yes       # machine holding data
yoke uninstall --no-backup --projects ~/work/app --yes

--projects accepts all, none, or comma-separated registered checkout paths. --yes never selects data loss or a project choice for you. The command leaves uv, the PATH line in your shell profile, and the GitHub App installed; remove the App in GitHub settings if desired. Push the removal commits made in the chosen checkouts. Project-owned edits and strategy documents are preserved by the existing project uninstall.

Related

• Maintaining a private fork
• Modes
• CLI and config
• Projects

If a fresh login shell cannot find yoke, run uv tool update-shell, check any shell configuration that overrides PATH, and open a new terminal. If uv cannot determine your shell, use the installer's printed export PATH=... command. yoke path verify probes your actual login shell; yoke path fix delegates configuration to uv. Yoke does not write its own shell startup blocks.