Install Roscoe

Roscoe ships as a single self-contained binary: the runtime, server, and web UI are all compiled in. There's nothing to install alongside it. No Node, no Bun, no Python. Each release publishes native builds for macOS (Apple Silicon and Intel), Linux (x64 and Arm64), and Windows x64.

The optional bits matter only if you plan to use AI nodes. Set ANTHROPIC_API_KEY in your environment, or put the Claude Code CLI on PATH (claude login once). Workflows built only from script, condition, human, and end nodes need neither.

1. Install#

curl -fsSL https://roscoe.run/install.sh | bash

The installer drops roscoe into ~/.roscoe/bin/, a user-owned directory, so it never needs sudo. A new shell doesn't have that folder on PATH, so the installer puts it there for you. It appends one line to your shell startup file (~/.zshrc for zsh, ~/.bashrc for bash, config.fish for fish). Run the installer twice and it won't add a second copy; open a new terminal, or source that file, and roscoe runs from anywhere.

Prefer to manage PATH yourself? Set ROSCOE_NO_MODIFY_PATH=1 and the installer leaves your startup files untouched. It prints the line to add instead:

export PATH="$HOME/.roscoe/bin:$PATH"

The installer only edits a startup file it recognises. Under any other shell, it prints that line rather than writing it.

If you'd rather drop the binary somewhere else, set ROSCOE_INSTALL_DIR. The script installs there instead. Point it at a system directory and you may need sudo:

ROSCOE_INSTALL_DIR="$HOME/.local/bin" curl -fsSL https://roscoe.run/install.sh | bash

On Windows x64, use PowerShell instead of the shell script:

irm https://roscoe.run/install.ps1 | iex

This installs roscoe.exe into %USERPROFILE%\.roscoe\bin\ and adds that folder to your user PATH. Open a new terminal for the change to take effect. ROSCOE_INSTALL_DIR overrides the location. ROSCOE_NO_MODIFY_PATH=1 skips the PATH edit if you'd rather set it yourself.

Verify the install:

roscoe --version

2. Initialise#

roscoe init

When run inside a git repo, this scaffolds both the global directory at ~/.roscoe/ and a project directory at <repo>/.roscoe/. It leaves your repo's root .gitignore untouched. It drops a small .roscoe/.gitignore, though, so the regenerated schema files (and a stray DB) aren't committed.

Your workflows and roscoe.yaml are tracked, so you can commit and share them. The database stays in the global home. Outside a repo it only touches ~/.roscoe/.

What gets created:

• roscoe.db — embedded SQLite store for runs and node traces.
• roscoe.yaml — config: available models, default model, ports, retry/timeout defaults. See roscoe.yaml.
• roscoe-config.schema.json — generated JSON Schema for editor autocomplete.
• workflows/ — your workflow library. The global directory ships with starter workflows, including demo-1-the-panel, demo-4-second-draft, and demo-8-smell-test. The project directory starts empty, for the team to fill in.
• .vscode/settings.json (project only) — wires the schema into the YAML language server so roscoe.yaml and *.workflow.yaml get autocomplete + validation in VS Code.

Useful flags:

See Workflow sources for how the two directories interact at run time.

3. Start the server#

roscoe serve

The combined web UI + API listens on http://localhost:7777. If 7777 is already in use, roscoe serve falls back to the next free port. Pass --port or set ROSCOE_PORT to pin it.

4. Staying up to date#

roscoe serve checks for new releases every 6 hours and pre-downloads the next binary into ~/.roscoe/updates/pending/. When one's ready, the sidebar chip in the web UI lights up, and the Settings → Updates panel shows a Staged badge. To apply it, stop the server (Ctrl-C in the terminal running roscoe serve) and start it again. The swap is near-instant, because the bytes are already on disk.

If you'd rather upgrade from the terminal:

roscoe update              # download + verify + swap, then restart serve
roscoe update --check      # exit 1 if a newer release exists, else 0
roscoe update --rollback   # restore the previous binary
roscoe version             # current version, then latest/update status below

Roscoe sha256-verifies the release manifest end to end. On macOS it also ad-hoc codesigns the new binary, so Apple Silicon doesn't refuse to launch it. To opt out, set updates.channel: off in roscoe.yaml or ROSCOE_DISABLE_UPDATE_CHECK=1 for one-off runs.

5. (Optional) Wire up Claude#

If you want Claude to drive workflows for you, register the MCP (Model Context Protocol) server.

For Claude Code (the CLI):

roscoe install-mcp

This adds a user-global roscoe entry to ~/.claude.json pointing at the installed binary, so it works across all your projects. (Use --project to write a project-local .mcp.json instead.) It also installs a /roscoe slash command. In Claude Code or Cowork, you can launch a workflow by typing /roscoe <workflow-name>.

For the Claude desktop app, pass --client claude-desktop:

roscoe install-mcp --client claude-desktop

This writes the same entry to the desktop app's config: ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, ~/.config/Claude/claude_desktop_config.json on Linux, %APPDATA%\Claude\claude_desktop_config.json on Windows, or the Microsoft Store build's per-package path under %LOCALAPPDATA%\Packages\Claude_*\. install-mcp writes to whichever path the app uses. Restart the app afterward. See MCP integration for what's exposed and how the pause/resume loop works.

Where to next#

• Core concepts — the vocabulary used everywhere else in these docs.
• Your first workflow — five minutes, end to end.