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 desktop app carrying the console and the whole CLI, for macOS and for Linux. It 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 whose build is signed and notarized.

Linux has the same desktop app, as a deb, an rpm or an AppImage, alongside the CLI installer. Windows has the desktop app too, as an installer that is not signed yet. Board sets up WSL2 and Ubuntu on first run and runs the toryo CLI and services inside it, not in PowerShell. Board defaults fresh distributions to Ubuntu-24.04. The Linux path is exercised in a container from install through setup, doctor, services, and database reads. Real Linux hardware and a real user systemd session remain unverified. See Linux & WSL2 and Windows.

toryo installs its own binaries. Setup can also offer tmux, Ollama, the GitHub CLI and the research browser, fetching a private Node for the browser when yours is missing or older than 20. It does not install a coding agent or git. toryo doctor checks the host contract and prints a repair command for anything missing.

Required:

• A coding agent, installed and signed in. toryo drives your own coding-agent sessions on any of Claude Code, Codex, GitHub Copilot or Cursor, and you can have more than one. The shipped sequences default to Claude Code unless you choose another agent and model. Capabilities differ by harness, so use the current matrix in Harnesses. You bring your own credentials: toryo licenses toryo and takes no margin on model usage.
• 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. Setup offers to install it (Homebrew on macOS, GitHub's apt repository on Debian and Ubuntu), and if it is not signed in, setup lists gh auth login as a step left for you.

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.

• Node 20 or newer, for the research browser and nothing else. A research run attaches a headless browser when a page will not yield to plain fetching, and that browser is Microsoft's Playwright MCP, which runs under npx. If your own node is 20 or newer, setup uses it. Otherwise, accepting the research browser also unpacks a pinned Node into ~/.toryo/runtime, with no sudo. toryo itself ships compiled binaries, so a host that never attaches a browser never needs node.

• A research browser (optional). Setup offers it, or install it later:

  toryo setup --install playwright-browser
  

  It is a few hundred megabytes of Chromium. Without it, research falls back to plain fetching and cannot read JS-heavy or bot-blocked pages. On Linux it also installs system libraries through apt, so that step needs sudo.

• Docker (optional). toryo stores everything in Postgres, and you choose how that Postgres runs. On a fresh install, setup defaults to Docker if it is running, and embedded pglite otherwise. pglite 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

Choose resource ownership up front. The database choice is not limited to Docker and pglite. You can also point toryo at PostgreSQL you operate. Install without provisioning, then run setup with the matching mode. For example:

curl -fsSL …/install.sh | TORYO_SKIP_SETUP=1 sh
~/.toryo/bin/toryo setup --runtime pglite
~/.toryo/bin/toryo setup --database-mode external \
  --database-url 'postgresql://admin:secret@db.example.com:5432/postgres'

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 --database-mode external --database-url <postgres-url>
toryo setup --ollama-mode external --ollama-host <ollama-url>
toryo setup --no-services      # provision without starting daemons
toryo setup --dry-run          # show what it would do
toryo setup --questions --json # list every question setup can ask, change nothing
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 installs exactly the tools you name and asks about nothing else. It takes any of tmux, ollama, ollama-models, playwright-browser, gh 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, the two models brain embeds and judges with, the GitHub CLI, and the research browser. 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 so you can decide whether to take it on a slow connection.

With no terminal and no explicit answers, setup asks nothing and installs no optional tools. This applies when curl | sh runs it without setup flags. 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. Board supplies explicit answers instead.

Answering setup from a script#

toryo setup --questions --json prints every question setup can ask on this machine, with its default and whether this host can take it, and changes nothing. Answer them by id with toryo setup --answers @answers.json (or inline JSON): setup then prompts for nothing, and an answer it cannot use, or an asked question left unanswered, stops it before it changes anything. Add --report-json to get a final JSON line listing what happened to each question, such as installed, present, declined or failed, and any step still left for you. This is how board's first-launch screen drives setup. --answers cannot be combined with --yes, --no-input, --install, --runtime, --database-mode, --database-url or the Ollama flags.

Choosing resource ownership#

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. Ollama is a separate choice, so either database ownership mode can use either local or external Ollama.

PostgreSQL: three modes#

An external PostgreSQL URL must name an administrative database. Its role needs permission to create and drop databases, terminate connections to a temporary probe database, and install the vector extension. Setup proves those exact capabilities with a temporary database before provisioning. It then creates one database per toryo app and runs toryo's own schema migrations against the selected server.

Ollama: two modes#

Local Ollama is the default. To use a server you operate instead, pass the validated pair together:

toryo setup --ollama-mode external --ollama-host https://ollama.example.com

Setup verifies the required model inventory when the endpoint answers. If it does not answer, setup still records the host and warns that toryo runs without brain enrichment until it does; Foreman reports it unavailable rather than failed. An external PostgreSQL that does not answer is still refused.

If models are missing, setup may offer to pull them to the remote server with your confirmation. In both external modes Foreman reports connectivity health, but it never starts or stops the external PostgreSQL or Ollama service.

Setup records TORYO_DATABASE_MODE and TORYO_OLLAMA_MODE in ~/.toryo/config.json, plus TORYO_DATABASE_URL or TORYO_OLLAMA_HOST for an external target. Credentials in the database URL should be protected like any other secret-bearing configuration file.

Comparing the two local database modes#

Both local 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.

Setup keeps a previously selected runtime. On a fresh install, it defaults to Docker when Docker is running and to pglite otherwise. Choose pglite explicitly with toryo setup --runtime pglite.

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

Which local mode 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 the selected database#

The authoritative setting is TORYO_DATABASE_MODE (see the CLI & contract reference), written into ~/.toryo/config.json by toryo setup. TORYO_DB_RUNTIME distinguishes Docker from pglite only for the two local modes.

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 local 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 between Docker and pglite 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 choose one first run.

In Board, open Help, choose a guided path, and follow its dock. The first path walks you through creating or selecting a project and starting useful work; you can switch paths or reopen the guide later.

From an agent session, use an installed skill:

• /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: tools, database, an enabled agent harness, license
toryo license status   # license state
toryo update           # self-update to the latest release
toryo update --check   # report what's available, change nothing
toryo runtime refresh # update the Node setup installed for the research browser
toryo update --quiescence # exit 0 when safe, 68 while work is active

toryo runtime refresh updates the private Node runtime. toryo update runs it for you.

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. It refuses with exit 68 while dispatch or sequence work is active; --force deliberately interrupts that work. Board can update its Apple Silicon build; Intel users replace the dmg manually. See Board and the CLI reference.

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 also removes ~/.toryo/runtime, which holds executables, not data. 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.