Skip to main content
Version: next

Installation

Routerly can be installed with a one-line script on macOS, Linux, and Windows. Docker is also supported for containerised deployments.


macOS / Linux​

curl -fsSL https://www.routerly.ai/install.sh | bash

The installer will:

  1. Detect your OS and architecture
  2. Download the latest Routerly release
  3. Install the service and CLI binaries
  4. Optionally configure a system daemon (systemd on Linux, launchd on macOS)
  5. Start the service

Installer flags​

You can customise the installation by passing flags after --:

curl -fsSL https://www.routerly.ai/install.sh | bash -s -- \
--yes # Non-interactive; accept all defaults
--scope user # Install for current user only (default)
--scope system # System-wide install (requires sudo)
--port 8080 # Use a custom port (default: 3000)
--public-url https://routerly.example.com # External URL of the service
--no-service # Skip service installation (CLI only)
--no-daemon # Skip auto-start setup
--no-linger # Linux user scope: do not run `loginctl enable-linger`
--channel current # Update channel: latest | current | next | stable | develop (default: current)
--version v0.2.0 # Install a specific version tag (overrides --channel)

By default, the installer fetches the current channel — the newest production-ready release. latest resolves to the same release; next tracks the validated pre-release line; stable installs the release explicitly promoted to stable (it moves only on promotion, so it can lag behind current); develop tracks the bleeding-edge, unreviewed line. Use --version vX.Y.Z to pin an exact version.

Breaking change

develop is not an alias for next: it is its own channel, the bleeding-edge line. An instance that had develop persisted under the old meaning now tracks the bleeding-edge line instead of next.

# Install the current release (default)
curl -fsSL https://www.routerly.ai/install.sh | bash

# Track the validated pre-release line
curl -fsSL https://www.routerly.ai/install.sh | bash -s -- --channel next

# Track the bleeding-edge line
curl -fsSL https://www.routerly.ai/install.sh | bash -s -- --channel develop

# Install a specific version
curl -fsSL https://www.routerly.ai/install.sh | bash -s -- --version v0.2.0

Installation scopes​

ScopeApp directoryCLI binary
user (default)~/.routerly/app/~/.local/bin/routerly
system/opt/routerly//usr/local/bin/routerly

The installer lists what it installed in .routerly-manifest inside the app directory. Updates and uninstall remove only those files (plus node_modules, dist and tsconfig.tsbuildinfo); anything else in the folder is left alone. A folder such as /opt/routerly that holds no Routerly install does not select the system scope: with --yes the scope is user. --scope user and --scope=user are equivalent; any other value is an error.

The service config and data directory depends on both scope and platform:

ScopeLinuxmacOSWindows
user~/.routerly/~/.routerly/%USERPROFILE%\.routerly\
system/var/lib/routerly//Library/Application Support/Routerly/C:\ProgramData\Routerly\
note

System scope requires sudo. The installer sets ROUTERLY_HOME in the daemon unit file so the service always reads the correct directory automatically.

CLI auth tokens are always per-user

Regardless of scope, each user's CLI credentials (JWT tokens, refresh tokens) are stored in ~/.routerly/cli/config.json with mode 0600. They are never placed in the system config directory.

Windows​

# Current release (default)
powershell -c "irm https://www.routerly.ai/install.ps1 | iex"

# Specific channel or version
powershell -c "& ([scriptblock]::Create((irm https://www.routerly.ai/install.ps1))) -Channel next"
powershell -c "& ([scriptblock]::Create((irm https://www.routerly.ai/install.ps1))) -Channel develop"
powershell -c "& ([scriptblock]::Create((irm https://www.routerly.ai/install.ps1))) -Version v0.2.0"

This installs Routerly as a Windows Service and adds the CLI to your PATH.

ParameterDescription
-Channellatest | current | next | stable | develop (default: current)
-VersionSpecific version tag, e.g. v0.2.0 (overrides -Channel)

develop is a real channel in its own right (the bleeding-edge line), not an alias for next.


Docker​

Two options are available: pull the pre-built image from Docker Hub (recommended), or build it yourself from source.

Option 1 — Pre-built image (Docker Hub)​

The official image is published on Docker Hub for linux/amd64 and linux/arm64.

Create a docker-compose.yml:

services:
routerly:
image: inebrio/routerly:v0.5.3
ports:
- "3000:3000"
volumes:
- routerly_data:/data
environment:
- ROUTERLY_HOME=/data
restart: unless-stopped
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
interval: 30s
timeout: 5s
retries: 3

volumes:
routerly_data:
docker compose up -d

docker run​

docker run -d \
--name routerly \
-p 3000:3000 \
-v routerly_data:/data \
-e ROUTERLY_HOME=/data \
--restart unless-stopped \
inebrio/routerly:v0.5.3

Option 2 — Build from source​

Use this if you want to run a local branch or a customised build.

git clone https://github.com/Inebrio/Routerly.git
cd Routerly
docker build -t routerly:local .
docker run -d \
--name routerly \
-p 3000:3000 \
-v routerly_data:/data \
-e ROUTERLY_HOME=/data \
--restart unless-stopped \
routerly:local

Or with docker-compose, add a docker-compose.override.yml next to your existing docker-compose.yml:

services:
routerly:
build: ./Routerly
image: routerly:local
docker compose up -d --build

Manual Installation (from source)​

Requirements: Node.js ≥ 20, npm ≥ 10

git clone https://github.com/Inebrio/Routerly.git
cd Routerly
npm install
npm run build
npm run start --workspace=packages/service

The CLI is available via:

node packages/cli/dist/index.js

Updating Routerly​

Run the installer again — it detects an existing installation and presents a menu:

# macOS / Linux
curl -fsSL https://www.routerly.ai/install.sh | bash

# Windows (PowerShell)
powershell -c "irm https://www.routerly.ai/install.ps1 | iex"

When an existing install is found you will see:

  Existing installation detected

What would you like to do?

1 Update — download & rebuild latest code, keep all settings
2 Reinstall — change components or settings (user data preserved)
3 Uninstall — remove Routerly from this machine
0 Cancel

Select 1 (or press Enter to accept the default) to download and rebuild the latest release. All configuration and user data are preserved.

To update without prompts (e.g. in a script or CI):

curl -fsSL https://www.routerly.ai/install.sh | bash -s -- --yes

Reinstalling​

Reinstalling lets you change installed components (service, CLI, dashboard) or reconfigure settings (port, scope, daemon) while keeping all user data intact.

Run the installer and select 2 at the menu:

# macOS / Linux
curl -fsSL https://www.routerly.ai/install.sh | bash

# Windows (PowerShell)
powershell -c "irm https://www.routerly.ai/install.ps1 | iex"

The wizard will walk you through the same questions as a fresh install, pre-filling your existing answers. All accounts, routers, models and usage history are preserved.


Uninstalling​

Run the installer and select 3 at the menu:

# macOS / Linux
curl -fsSL https://www.routerly.ai/install.sh | bash

# Windows (PowerShell)
powershell -c "irm https://www.routerly.ai/install.ps1 | iex"

The uninstall flow will:

  1. Stop and remove the system daemon (systemd / launchd / Windows Service)
  2. Remove the application files the installer created (not other files in the same folder) and the CLI binary
  3. Ask whether to also delete user data (~/.routerly/ — accounts, settings, usage history)
Data preservation

If you answer No to the data removal prompt, all accounts and history are kept. Running the installer again will detect the existing data and offer to resume from where you left off.


Auto-start Configuration​

The installer can configure Routerly to start automatically on boot:

OSScopeMethodLocation
Linuxusersystemd user service~/.config/systemd/user/routerly.service
Linuxsystemsystemd system service/etc/systemd/system/routerly.service
macOSuserlaunchd LaunchAgent~/Library/LaunchAgents/ai.routerly.service.plist
macOSsystemlaunchd LaunchDaemon/Library/LaunchDaemons/ai.routerly.service.plist
Windows—Windows Servicevia sc.exe

On Linux with user scope the installer also runs loginctl enable-linger <user>, so the service keeps running after you log out and starts at boot. Pass --no-linger to skip it, or run the command yourself if it failed. The uninstaller leaves linger as it is, because other user services may depend on it (loginctl disable-linger <user> to undo).

To start/stop manually:

# Linux (user scope)
systemctl --user start routerly
systemctl --user stop routerly

# macOS (user scope)
launchctl load ~/Library/LaunchAgents/ai.routerly.service.plist
launchctl unload ~/Library/LaunchAgents/ai.routerly.service.plist

Verifying the Installation​

routerly status

You should see the service URL, version, and a reachability check. Then open the dashboard:

http://localhost:3000/dashboard

→ Continue to Quick Start to set up your first model and router.