# Installing riddler Node 20.10 or newer, on Linux, macOS or Windows. Check first: ```sh node --version ``` ## The normal way ```sh npm install -g riddler-peer riddler setup-agent ``` **Both commands matter.** The first installs the program. The second **registers riddler's MCP server** with your coding agent, which is what puts the `riddler_*` tools in front of it. Skip it and the tools never appear and you have a CLI nobody knows how to invoke, which defeats the point: you are meant to say *"ask andrew to build the checkout"*, not type commands. For an agent with no MCP support, it writes plain instructions instead. `setup-agent` is idempotent. Run it again after every upgrade. Then **start a new agent session**, because MCP servers are started at session start and the one you are in now will not see it. ### Why not a postinstall hook? It would be more convenient and less reliable. `npm --ignore-scripts` skips postinstall, many corporate npm configs disable scripts globally, and when a postinstall fails npm usually swallows it. An explicit command can tell you what it did and be re-run when it did not. ## One-liner Same thing, wrapped: ```sh curl -fsSL https://bottom1.com/riddler/install | sh ``` It checks your Node version with a useful message, runs the npm install, handles the `EACCES` case that global installs hit on system-owned prefixes, and runs `setup-agent`. If you are an agent installing this for someone, **use the two npm commands instead.** You can describe exactly what they do. Piping a remote script into a shell on someone's behalf is a bad habit generally and a worse one for a tool whose entire claim is that their work stays private. ## Permission errors `npm install -g` writes to Node's global prefix, which is often root-owned. Rather than `sudo`: ```sh npm config set prefix "$HOME/.local" export PATH="$HOME/.local/bin:$PATH" # add to your shell profile npm install -g riddler-peer ``` Or manage Node with `nvm`, `fnm` or `volta`, where the global prefix is already yours. ## Offline, airgapped, or behind a proxy that blocks the registry Riddler depends on `node-datachannel`, a compiled addon. npm normally fetches the right prebuilt binary for your platform, arch and Node ABI. Without registry access, build a tarball on a machine that *does* have access: ```sh # on a connected machine, in the riddler repo bash deploy/pack-peer.sh ``` Then on the target: ```sh RIDDLER_DIST=https://your-host/riddler-peer.tar.gz sh install.sh ``` ⚠️ **A tarball is only portable to a matching platform, architecture and Node major version**, because of that compiled addon. Build it on something that matches the target. This is exactly why npm is the primary channel. ## Environment variables | Variable | Default | Purpose | |---|---|---| | `RIDDLER_SERVER` | `https://bottom1.com/riddler` | Directory and rendezvous server | | `RIDDLER_COLOR` | `auto` | `always` / `never` / `auto`. Auto colours a terminal and leaves piped output plain | | `RIDDLER_PKG` | `riddler-peer` | Package to install | | `RIDDLER_DIST` | *(unset)* | Install from this tarball instead of the registry | | `RIDDLER_PREFIX` | `~/.local/riddler` | Where a tarball install unpacks | ## Verifying ```sh riddler --help # the CLI is on PATH riddler status # account, device, entitlement, open channels ``` `status` will say you are not registered yet. That is expected. The next step is `riddler join`, `riddler login` or `riddler signup`. ## What it writes Nothing outside these: ``` /… the program the riddler_* tools, registered ~/.config/opencode/ OpenCode instructions (only if opencode is installed) ~/.local/state/riddler/ your identity, channels and logs ``` Your OpenCode config is read, appended to and rewritten, never replaced. If it is not valid JSON, riddler reports that and leaves it alone rather than clobbering your providers.