# 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](https://claude.ai/code) on `PATH` (`claude login` once).
Workflows built only from `script`, `condition`, `human`, and `end` nodes
need neither.

## 1. Install

```bash
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:

```bash
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`:

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

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

```powershell
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:

```bash
roscoe --version
```

## 2. Initialise

```bash
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](/docs/configuration/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:

| Flag            | Behaviour                                          |
| --------------- | -------------------------------------------------- |
| `--global-only` | Only touch `~/.roscoe/`, skip repo scaffolding.    |
| `--repo-only`   | Only scaffold `<repo>/.roscoe/`, skip global init. |
| `--force`       | Overwrite existing example workflow files.         |
| `--no-examples` | Skip seeding the starter workflows.                |

See [Workflow sources](/docs/configuration/workflow-sources) for how the two
directories interact at run time.

## 3. Start the server

```bash
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:

```bash
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):

```bash
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`:

```bash
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](/docs/running/mcp) for what's exposed and how the
pause/resume loop works.

## Where to next

- [Core concepts](/docs/getting-started/concepts) — the vocabulary used
  everywhere else in these docs.
- [Your first workflow](/docs/getting-started/first-workflow) — five
  minutes, end to end.