Get started

Install a standalone release

GitHub Releases provides standalone archives for Windows, macOS, and Linux, each for x64 and ARM64. They include Node.js, npm, the host's installed dependencies, the finished web interface, plugins, and platform tools. No existing Node.js, npm, pnpm, or source checkout is needed. Linux builds target glibc systems, not Alpine/musl.

Install for you or for all users

An installer script installs the archive for this machine. You choose the scope: the current user (the default) or all users of the machine.

The versions go to lib/ragents (Windows: versions) below that folder, the command to bin. On macOS or Linux, for the current user:

curl -fsSL https://github.com/SchlenkR/RAgents/releases/latest/download/install.sh | sh

For all users:

curl -fsSL https://github.com/SchlenkR/RAgents/releases/latest/download/install.sh | sh -s -- --global

The shell installer does not edit your startup files. ~/.local/bin is often not on the PATH, on macOS by default; the installer then prints the line to add for your shell, for zsh this line in ~/.zshrc:

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

Open a new terminal afterwards, or run the command by its full path. /usr/local/bin is on the default PATH of macOS and common Linux distributions.

On Windows, in PowerShell, for the current user:

& ([scriptblock]::Create((irm https://github.com/SchlenkR/RAgents/releases/latest/download/install.ps1)))

For all users, in a PowerShell started with "Run as administrator":

& ([scriptblock]::Create((irm https://github.com/SchlenkR/RAgents/releases/latest/download/install.ps1))) -Global

The Windows installer adds its bin folder to the user or machine PATH; open a new terminal afterwards. Without an elevated PowerShell, -Global stops with a message instead of installing for the current user. Use this script block form rather than irm ... | iex: only it passes parameters to the script.

Further options follow sh -s -- in the shell and the closing parenthesis in PowerShell:

• --version 0.1.21 or -Version 0.1.21 installs that release instead of the latest.
• --prefix /absolute/folder or -Prefix C:\Apps\RAgents installs into another folder. The scope still decides about administrator access and, on Windows, which PATH changes.
• -NoPathUpdate leaves the Windows PATH unchanged.
• --help or -Help lists all options.

Both installers verify the archive against the release's SHA256SUMS, check that the command starts, and prepare the installation completely before they switch the active version, so a running host never writes into the installation folder. They refuse to replace a ragents command they did not create, for example one from npm. If another ragents command comes first on your PATH, or the other scope still holds an installation, the installer warns and prints the command that removes it; it never removes another installation itself. ragents --version shows the active version.

Alternatively, unpack the matching archive yourself and run bin/ragents or bin/ragents.cmd from it. Its first command then writes links into that folder, so the folder must be writable.

Update and uninstall

Run the install command of your scope again to update. The new release is installed next to the previous ones, which remain installed; the command switches only after the new version has passed its checks. To switch back, pass the older version with --version or -Version. Stop running hosts before switching versions and restart them afterwards.

To uninstall, add --uninstall or -Uninstall to the command of your scope, for example:

curl -fsSL https://github.com/SchlenkR/RAgents/releases/latest/download/install.sh | sh -s -- --uninstall

& ([scriptblock]::Create((irm https://github.com/SchlenkR/RAgents/releases/latest/download/install.ps1))) -Uninstall

This removes the command and every installed version, on Windows also the PATH entry. A PATH line you added to a startup file stays. Settings and runs stay in each user's data directory, ~/.local/share/ragents or %LOCALAPPDATA%\ragents; delete it to remove them as well.

First start

The included profiles read the OpenRouter key from the environment variable OPENROUTER_API_KEY; no .env file is loaded. Set it in the shell that starts RAgents or in its startup file, then start the core profile:

export OPENROUTER_API_KEY=<your-key>
ragents start core

In PowerShell, set it with $env:OPENROUTER_API_KEY = "<your-key>". The start provisions the profile's tools into the user's data directory, for example ~/.local/share/ragents/core, and then serves the interface at http://localhost:4710. Without the variable, it stops before the server starts:

.../ragents.config.core.ts: ragents.product.OPENROUTER_API_KEY refers with env("OPENROUTER_API_KEY") to an environment variable that is not set in this shell. ...
Provisioning ended with code 1

The C# and F# diagnostics of core (ragents.lsp-roslyn and ragents.lsp-fsharp) need the .NET 10 SDK with dotnet on the PATH. Without it, the start stops after provisioning:

ragents.lsp-fsharp: missing: dotnet is missing on this machine; install the .NET SDK from https://dotnet.microsoft.com/download and make sure dotnet is on the PATH
ragents.lsp-roslyn: missing: dotnet is missing on this machine; install the .NET SDK from https://dotnet.microsoft.com/download and make sure dotnet is on the PATH
Provisioning ended with code 1

Install the SDK and start again, or start an own profile without these two plugins, see Custom profiles and plugins. The archive includes no model credentials, Chromium, language servers, or development SDKs. Provisioning fetches Chromium and the language servers; on Linux it installs Chromium's system libraries with sudo. These requirements are the same for the npm package. ragents --help lists the other commands, and Configure model access and start describes the model settings.

The process sandbox has platform prerequisites too: Linux needs bubblewrap, socat, and working user namespaces; the standalone starter exposes its bundled ripgrep automatically. On Windows, explicitly set PROCESS_SANDBOX: "off" in the profile's ragents.workspace section. See Server process sandbox for setup and configuration.

Install from npm

With Node.js 22.19 or newer, install the command globally:

npm install -g @schlenkr/ragents
ragents start core

Or run it through npx without a global installation:

npx --yes @schlenkr/ragents start core

The first start is the same as for a standalone release, see First start: OPENROUTER_API_KEY must be set, and the C# and F# diagnostics of core need the .NET 10 SDK. Then open http://localhost:4710. Other subcommands work the same way, for example npx --yes @schlenkr/ragents connect <server-url>.

Install from the repository

The application is built from the repository with Node.js and pnpm. Run these commands from the repository root:

pnpm install
pnpm build:agent
pnpm provision core

The second command generates type declarations for the agent runtime and is required after a fresh clone. The third downloads the tools required by the profile's plugins, such as language servers and the browser, to <data-directory>/tools/<plugin-id>/. For each plugin it reports ready, installed, or missing: <reason>; a missing prerequisite explains what must be done manually, such as installing dotnet. Running it again downloads nothing unnecessarily. The core profile contains the neutral workspace with chat, agents, TypeScript functions, and mini-apps. Its settings are in ragents.config.core.ts. A profile selects plugins, models, and configuration; it is not a single agent task. showcase (ragents.config.showcase.ts) is the same profile plus the included examples. pnpm provision showcase installs its tools in its own data directory.

Configure model access and start

The model integration uses OpenRouter. In the profile file's ragents.product section, configure OPENROUTER_API_KEY as a reference to your own environment variable, for example env("RAGENTS_MODEL_API_KEY"), and provide its value in your shell or service environment. The included core, showcase, and developer profiles use env("OPENROUTER_API_KEY") and expect that exact environment variable. Startup fails if it is missing. Existing environment variables take precedence over profile values; no .env file is loaded. Startup reports a missing referenced variable as an error. Configured models and reasoning levels must be valid in the available model catalog.

A profile can also name its models by alias: MODEL_ALIASES in the host section lists objects with alias, model as provider/model, an optional default thinking level, optional thinkingLevels that map the levels the alias offers onto levels of its model (for example { off: "low", low: "low", medium: "high" } for a model that always reasons and has no medium), and the model's compaction values: the context size in tokens at which an agent compacts (threshold), how much recent context stays verbatim (keepRecentTokens), and the summary budget (summaryTokens). AGENT_PROVIDER: "alias" makes the product use them. The interface, the chat, and the journal then show only the alias names.

An alias can also point to a self-hosted OpenAI-compatible server. MODEL_PROVIDERS in the host section lists such servers with id, baseUrl (up to /v1), apiKey: env("..."), optional compat, and their models (id, contextWindow, maxTokens, reasoning, input, optional thinkingLevelMap); an alias then names <id>/<model>. For a Qwen chat template, as served by oMLX, set compat: { thinkingFormat: "qwen-chat-template" }, so the alias's thinking levels reach the server. Details and an example in docs/spec/profiles.md.

Alternatively, a profile can obtain its models from another RAgents server running the ragents.model-relay plugin, which offers that server's MODEL_ALIASES with their thinking levels and compaction values: set AGENT_PROVIDER: "relay", point RELAY_URL to that server, use RELAY_TOKEN: env("...") with a user's personal token there, and use relay aliases for every model key. Only the relay server can see which model is behind an alias. Its log at plugins/ragents.model-relay/relay.log records the user, alias, target, and token count for each request.

Then start the neutral profile:

scripts/start.sh core

The script builds the plugins, builds the web application and help if they are missing or outdated, then starts the server. The interface is available at http://localhost:4710; runtime data is stored in ~/.local/share/ragents/core. PORT and DATA_DIR can override these defaults. scripts/start.sh showcase starts the same profile with examples on port 4713 and stores data in ~/.local/share/ragents/showcase; both can run side by side. Without a user list, sign-in is disabled. Users and permissions explains how to configure access. Additional language servers must be installed separately for their diagnostic functions; the first chat message does not start them.

The fixed server port is configured as host.PORT in the profile file. If it is occupied, startup fails. The address stays fixed and a running instance is not terminated. An explicitly set PORT must be between 1 and 65535; 0 is invalid. The final server message displays the URL. A warning about JavaScript bundle size does not prevent startup.

Build after changes

Server changes take effect after a restart. There is one web interface for every profile, built with the host into apps/web/dist; plugin interfaces are loaded at runtime from the plugin bundles of the running profile. scripts/start.sh rebuilds outdated plugins before every start and the web interface only when it is missing or no longer matches its sources, so restarting is enough after changes. pnpm build:web builds it directly. Started any other way from a checkout (pnpm start, ragents run, ragents start, the VS Code extension), the server refuses outdated built-in bundles or an outdated interface and names pnpm build:plugins or pnpm build:web. pnpm check runs the project checks, including tests, type checking, and the web build. pnpm build:package creates the host as an npm package for machines without a checkout, and pnpm release publishes it together with the extension and standalone archives (see development.md). The question mark next to Settings opens the included help. For separate static hosting, pnpm generate:homepage creates the same website under docs/homepage/dist.

Create your first run

Start shows recent runs and the same templates in the browser and VS Code: "New chat" or the server's default template first, then skill templates with a prepared task and script templates with programmed setups. "New chat" opens an empty run whose task you write in its chat; a template starts with one click. Some templates collect values in a setup dialog first ("Set up"); a skill template then continues in the preparation chat. There you can discuss the task, give a clear go-ahead such as "Start", or choose "Create run". Merely confirming a detail does not start anything. In the browser a new run always works on the server; only VS Code and ragents run bind a run to a workstation.

A click shows its effect at once: either the run's progress appears, or the chosen entry shows a spinner and "Starting ..." while the other entries stay locked until the run opens or the start fails; a run script in the run header's "Run script" list does the same. While a template starts, the panel shows its progress in the chat area and reserves the bottom status bar, keeping the notice in place when the run connects.

Inside the run, the coordinator processes the task. Additional agents and mini-apps appear on the surface when the workflow creates them. The global coordinator in the header has its own conversation and can oversee several runs. The journal and "Executions" tab make events and TypeScript calls traceable.

Use chat and mini-apps

Activated visible mini-apps become available automatically, including those from an embedded setup. Programs cannot arrange the host interface. Runs saved with removed layout functions or placements are locked with an explanation; their original files are kept. Start a new run with updated programs.

Wide browser runs start with Chat beside the mini-apps; narrow ones use one tab group. Drag tabs onto the docking guides to arrange areas or merge them. Chat and visited apps keep their input through switches and moves. New apps appear without taking focus; unavailable apps disappear. Close windows with X. The run header keeps a button for every window; a pressed button is visible, and clicking another one shows that window. Drag a header button by its grip to reorder the buttons, or onto the docking guides to place that window. "Empty space" in the header adds an empty pane that holds a place until you drop a window onto it. When the header is too narrow for the buttons, they all move into one "All windows" menu.

In VS Code, clicking an app opens or focuses its editor tab. VS Code controls where that tab appears. Questions and news stay in chat. The selector below the input chooses the addressee; the run coordinator is selected by default.

Source: docs/operations.md, docs/usage.md. This chapter as Markdown.

Use Web and VS Code