Getting started

This walks a new developer from nothing to a first toryo task: install → activate → register a project → run.

toryo ships as one download: a dmg per Mac architecture, each carrying the desktop console and the whole CLI. The app installs and provisions everything on first launch, so there is no second artifact and no terminal step to get running.

Requirements#

macOS, Apple Silicon or Intel. That is the platform this guide describes and the only one with a desktop app.

Linux and Windows-through-WSL2 have a CLI install, by curl | sh rather than a .dmg, and no app. Nobody has yet run it on a real Linux or Windows machine. See Linux & WSL2 for what that install covers and what it does not.

toryo installs its own binaries, but it does not install the tools below. Get them in place first; toryo doctor checks every one of them and prints the exact command to fix anything missing.

Required:

• A coding agent, installed and signed in. toryo drives your own coding-agent sessions on any of Claude Code, Codex or GitHub Copilot, and you can have more than one. Claude Code is the one to start with: it is the only harness that supports every capability toryo can ask for, and the shipped sequences assume it unless you say otherwise. You bring your own credentials: toryo licenses toryo and takes no margin on model usage. See Harnesses.
• git.
• tmux (brew install tmux). Every agent session runs inside its own tmux session, which is what lets a long task keep working after you close the window, and lets you attach to a running one.
• GitHub CLI (brew install gh), signed in (gh auth login). The coding sequence opens and updates a pull request as part of its normal run, so /toryo-code fails partway through without it.

Recommended:

• Ollama (brew install ollama), plus two models:

  ollama pull nomic-embed-text   # embeddings for memory and library search
  ollama pull llama3.1           # the judge on global memory writes
  

  toryo runs without it, but the knowledge plane is much weaker: semantic search falls back to keyword matching, and every global memory write queues for review instead of being judged. Both models are needed. The embedding model cannot serve the judge, and a daemon with only that one embeds fine while failing every judgement.

• Docker (optional). toryo stores everything in Postgres, and you choose how that Postgres runs. Docker is the default; the embedded pglite runtime needs no Docker at all. See Choosing a database runtime.

1. Install#

Go to the downloads page and take the dmg for your Mac (Apple Silicon or Intel). Open it and drag Toryo to Applications. The build is signed and notarized, so it opens without a Gatekeeper warning.

Launch it. On first run the app installs the toryo CLI into ~/.toryo/bin, brings up the database, runs every migration, and starts the background services, streaming its progress as it goes. A first run takes a few minutes, mostly pulling the Postgres image.

That is the whole install. When it finishes you have both the console and the toryo command line.

Running headless instead#

On a CI host or a server with no desktop, install the CLI on its own:

curl -fsSL https://raw.githubusercontent.com/ForceBuilders/toryo-releases/main/install.sh | sh

That detects your architecture, downloads the latest release, verifies it against SHA256SUMS, extracts into ~/.toryo/bin, and runs toryo setup and toryo skills install. Overrides go before sh, not before curl, or the installer never sees them:

curl -fsSL …/install.sh | TORYO_VERSION=0.1.0 sh

No Docker? The runtime is chosen at provisioning and is not reversible without a pg_dump, so pick it up front: install without provisioning, then provision onto pglite.

curl -fsSL …/install.sh | TORYO_SKIP_SETUP=1 sh
~/.toryo/bin/toryo setup --runtime pglite

2. Provision (toryo setup)#

The app does this for you on first launch, and curl | sh does it too. Run it yourself only to change something or to repair an install. It is idempotent and safe to re-run.

toryo setup                    # asks what it needs, then provisions
toryo setup --runtime pglite   # no Docker: embedded pglite runtime, no runtime prompt
toryo setup --no-services      # provision without starting daemons
toryo setup --dry-run          # show what it would do
toryo setup --yes              # accept every offer without asking
toryo setup --no-input         # never prompt, never install
toryo setup --install tmux     # install exactly these, ask about nothing

--install is how a GUI drives setup: board asks its own questions on the first launch screen and passes the answers down, because it spawns setup with piped stdio and so has no terminal for setup to prompt at. It takes any of tmux, ollama, ollama-models comma-separated, or none. Omitting it is not the same as --install none: one still prompts, the other is a decision to install nothing.

Setup installs the CLI binaries into ~/.toryo/bin if they are not already there, creates the ~/.toryo state directories and config.json, adds ~/.toryo/bin to your PATH (in a managed block in your shell rc, so it applies to new shells), brings up the database, runs every app's migrations, installs the foreman watch background supervisor as a launchd agent, and offers to wire toryo's MCP server into the clients it finds (Claude Code, Claude Desktop, Codex, GitHub Copilot, Cursor).

That last step is an offer rather than a service: it edits config files toryo does not own (~/.claude.json for Claude Code, claude_desktop_config.json for Claude Desktop, and one apiece for the rest), so it backs each one up first and an unattended run never touches them silently. Once wired, an ordinary agent session can search your knowledge plane, look at what is running, and start work. See MCP.

What it offers to install#

Run from a terminal, setup checks the host tooling and offers to install whatever is missing: tmux (which every Claude session runs inside), ollama, and the two models brain embeds and judges with. It uses Homebrew on macOS and apt or the vendor installer on Linux, so it may ask for your password.

Every offer defaults to yes, and you can decline any of them; setup prints the command so you can finish by hand later. The model pull states its download size before it starts, because it is the one offer large enough to matter on a slow connection.

With no terminal, setup asks nothing and installs nothing. That is the case when the desktop app provisions on first launch and when curl | sh runs it, and in both there is no way to answer a question. It lists what it skipped and carries on. Pass --yes to take every default unattended, or --no-input to pin the ask-nothing behaviour even on a terminal.

Choosing a database runtime#

toryo keeps its state in Postgres: one database per app, holding your job queue, schedules, sequence runs, and the whole knowledge plane. You choose how that Postgres runs.

Both options are real Postgres, same dialect, same pgvector semantic search, same full-text search, identical schema. No toryo feature is available on one and not the other. This is an operational choice, not a capability one.

Docker is the default. Choose pglite explicitly with toryo setup --runtime pglite.

Port 5433 is deliberate: it avoids colliding with a Postgres you already run on 5432.

Which to pick#

Docker if you have it, or would not mind having it. It is the recommended default for heavy use: several projects, many concurrent runs, a large knowledge base.

pglite if you want no Docker dependency at all, on a machine where Docker Desktop is unwelcome or unavailable. It is a genuinely self-contained install.

The one real limitation of pglite#

Every toryo process reaches pglite through a socket server that multiplexes all of them onto a single backend session. Queries, and whole transactions with them, therefore run one at a time per database, and a long transaction makes other processes wait behind it.

Toryo's writes are short, so this is fine in normal use. It is why Docker stays the recommendation once you are running several projects with real concurrency.

Checking which you're on#

The setting is TORYO_DB_RUNTIME (see the CLI & contract reference), written into ~/.toryo/config.json by toryo setup. That file is the direct answer.

toryo doctor shows it too, if less directly: its Postgres config line reads localhost:5433 under Docker and a socket path under pglite, and the Docker check reports itself as not required when you are on pglite. Either way it tells you whether the database is actually reachable.

The runtime is normally chosen once, at provisioning, and left alone. Worth knowing if you do change it: each runtime keeps its data in its own place, so switching points toryo at a fresh, empty store rather than carrying your existing one across. Nothing is lost, since the original is still there if you switch back, and moving data between them is a pg_dump and restore for now.

3. Activate#

toryo requires a license, so this step is not optional. Nothing runs until it is done: foreman stays up but supervises no services.

In the app, the activation dialog opens on its own when it finds no license:

• Evaluating on your own? Choose Start free trial and enter your email. That is the whole step, and you get 14 days of the full product.
• Joining a team? Choose Enter license key and give it the email address and key your administrator issued you. Both halves are required.

From a terminal, which is the only route on a headless install:

toryo license trial --email you@example.com              # 14-day trial
toryo license activate --email you@example.com <key>     # a team key
toryo license status                                     # confirm it took

Both commands require the email; a key alone is not enough.

See Licensing & activation for what a seat covers, what happens when a trial ends, and how to get unblocked.

4. Install the skills#

Both installers do this for you. Run it yourself after an update, or if you skipped it:

toryo skills install

This copies toryo's operator /-commands into both user-level skills roots, ~/.claude/skills (Claude Code, Cursor) and ~/.agents/skills (codex, Copilot, Cursor), namespaced toryo-<name> (so /toryo-code, /toryo-review, …) and rewritten to call the installed toryo <app> binary. See the Skills reference.

5. Register a project and run#

A project is a named reference to a directory toryo runs tasks against.

toryo project add --name web --root /path/to/your/repo
toryo project list

Then, from inside Claude Code:

• /toryo-code web "add a rate limiter to the login route" runs the full coding sequence (plan → approve → implement → review → merge gate).
• /toryo-task web "summarize how auth works in this repo" runs a single quick session, no gates.
• /toryo-review web reviews the whole project against your rules and everything the knowledge plane knows about it.
• /toryo-status shows recent runs.

The full set is in the Skills reference, which is generated from the installed skills, so it is the list that is actually on your machine.

You can also ask an ordinary Claude session what toryo knows and what it is doing, from Claude Code or Claude Desktop. See MCP.

Managing your install#

toryo foreman check    # are the background services healthy?
toryo doctor           # host preflight: bun, docker, tmux, claude, license
toryo license status   # license state
toryo update           # self-update to the latest release
toryo update --check   # report what's available, change nothing

toryo update swaps the binaries in ~/.toryo/bin for an installed release, or pulls and rebuilds when you are running from a source checkout. It updates the CLI only: the app does not self-update yet, so to get a newer console, download the dmg again and replace it in Applications.

Uninstalling#

toryo uninstall           # remove toryo, keep the databases
toryo uninstall --purge   # remove the databases too
toryo uninstall --dry-run # show what it would remove

Deleting Toryo.app is not enough on its own: the install also leaves a running launchd agent, ~/.toryo, and a managed block in your shell rc. toryo uninstall takes all of it, in the reverse of the order setup built it.

The default is recoverable: it removes the binaries, the supervisor, the shell block, the skills and the MCP registration, and keeps ~/.toryo so a reinstall finds your brain, memory and library where it left them. It prints what it kept.

--purge also deletes ~/.toryo and, on the docker runtime, the toryo-pgdata volume that lives outside it. That erases everything toryo has learned and cannot be undone. Both tiers ask first; pass --yes to skip the question, which is required when there is no terminal to ask at.

After it finishes, drag Toryo.app to the trash.

The board desktop console gives you the same view with a UI: services, the job queue, sequence runs, schedules, the knowledge plane, ideas, and settings.