Install

VeloxSaarthi ships as a single self-contained vlx binary per OS — no Node, Bun, or source tree required on the machine. The binary keeps all of its state under ~/.vlx/ and updates itself from the release channel every time the daemon starts.

---

Prerequisites

The binary shells out to these tools at runtime — install them first:

Tool	Min version	Why
git	2.x	Clones the client repo, manages per-run worktrees, pushes PRs
Node.js + npm	20+	Runs the claude-code and claude-agent-acp CLIs below
claude-code CLI	latest	The underlying Claude Code agent
claude-agent-acp	0.37.0	ACP bridge the daemon spawns to drive each actor session

Install both CLIs globally with npm, then authenticate:

npm install -g @anthropic-ai/claude-code @agentclientprotocol/claude-agent-acp
claude          # run once to authenticate

Both must be on the PATH the daemon sees — verify with claude --version and claude-agent-acp --version (on Windows: cmd /c claude-agent-acp --version). Set cleanupPeriodDays: 90 in ~/.claude/settings.json so Claude sessions outlive the 72-hour story timeout.

Windows, macOS, and Linux are all first-class

The daemon runs natively on all three. WSL2 is not required on Windows.

---

1. Install VeloxSaarthi

Grab the binary for your platform (current release: v0.0.61). On Windows, the install command below saves the binary to %USERPROFILE%\.vlx\bin and adds that folder to your user PATH; on macOS/Linux put it on PATH yourself. The links are immutable, versioned URLs stamped to the latest release:

Platform	Download
Windows x64	vlx-windows-x64.exe
macOS (Apple Silicon)	vlx-darwin-arm64
Linux x64	vlx-linux-x64

Windows

# One-time install: saves vlx into %USERPROFILE%\.vlx\bin and adds that folder to
# your user PATH (persisted for future terminals; also set for this one).
$b="$env:USERPROFILE\.vlx\bin"; New-Item -Force -ItemType Directory $b | Out-Null; curl.exe -L -o "$b\vlx.exe" https://dl.saarthi.bot/releases/v0.0.61/vlx-windows-x64.exe; $u=[Environment]::GetEnvironmentVariable('Path','User'); if ($u -notlike "*$b*") { [Environment]::SetEnvironmentVariable('Path',"$b;$u",'User') }; $env:Path="$b;$env:Path"

macOS

mkdir -p ~/.vlx/bin
curl -L -o ~/.vlx/bin/vlx https://dl.saarthi.bot/releases/v0.0.61/vlx-darwin-arm64
chmod +x ~/.vlx/bin/vlx
export PATH="$HOME/.vlx/bin:$PATH"   # add to your shell profile

Linux

mkdir -p ~/.vlx/bin
curl -L -o ~/.vlx/bin/vlx https://dl.saarthi.bot/releases/v0.0.61/vlx-linux-x64
chmod +x ~/.vlx/bin/vlx
export PATH="$HOME/.vlx/bin:$PATH"   # add to your shell profile

On macOS and Linux, verify after putting the binary on PATH:

vlx --version

Until release signing is configured, Windows may show an unknown-publisher warning.

Previously installed via the Windows MSI? The MSI is discontinued (it could not self-update). Uninstall "VeloxSaarthi" from Settings → Apps — it never removes %USERPROFILE%\.vlx — then install the portable binary above.

---

2. Run the guided setup

vlx init

The wizard prompts for:

• Azure DevOps org URL, project, and repository name
• Base branch (default main) and where to clone the client repo (default ~/.vlx/repos/<repo>)
• ADO Personal Access Token — scopes Work Items (Read/Write) + Code (Read/Write)
• Telegram bot token, group chat ID, and authorized user IDs

It then resolves the repository ID via the ADO API, clones the repo, writes ~/.vlx/vlx.yaml and ~/.vlx/secrets/global.env, and runs the database migrations. No hand-editing required — but see Configure for what the generated config means and how to adjust it.

How to obtain	Where
ADO PAT	dev.azure.com → User settings → Personal access tokens
Telegram bot token	Talk to @BotFather: /newbot
Telegram group chat ID	Add the bot to the group, then call the Telegram getUpdates API

Security

These are bootstrap credentials for the daemon itself. They live in ~/.vlx/secrets/global.env (mode 600 on POSIX) and are auto-loaded at startup. Do not pass them through any agent channel. See Security.

---

3. Start the daemon

vlx daemon

The daemon runs in the foreground of your terminal; stop it with Ctrl+C. On start it checks the release channel, self-updates if a newer version is published (see below), verifies database integrity, takes a daily backup, applies pending migrations, then begins polling. Watch progress in the Telegram group or the pretty-printed log output.

---

Self-update

Every installation checks https://dl.saarthi.bot/releases/latest.json on every daemon start. If a newer version is published, the daemon downloads it, verifies the SHA-256, swaps the binary, and restarts itself.

• vlx update — check and apply an update immediately
• vlx daemon --no-update or VLX_NO_UPDATE=1 — skip the on-start check
• VLX_UPDATE_URL=<base-url> — point at a different release channel

A check failure (offline, blob outage) is never fatal: the daemon logs a warning and starts on the current version.

---

Where everything lives

Path	Contents
~/.vlx/vlx.yaml	Configuration (generated by vlx init)
~/.vlx/secrets/global.env	Bootstrap credentials, auto-loaded at startup
~/.vlx/state.db	SQLite state (runs, queue, events, tracked PRs)
~/.vlx/backups/	Daily VACUUM INTO snapshots
~/.vlx/repos/<repo>	Default clone location for the client repo
~/.vlx/worktrees/	Per-run git worktrees
~/.vlx/bin/	Installed vlx binary (Windows) + self-update staging

Because all state is under ~/.vlx, you can run vlx from any directory. Override the root with VLX_HOME.

---

Running from source (development)

For working on VeloxSaarthi itself you need git, Node 20+, Bun 1.x, and the claude-code + claude-agent-acp CLIs (see Prerequisites):

git clone <repo-url> ~/veloxsaarthi
cd ~/veloxsaarthi
bun install
bun run src/cli.ts init      # or reuse an existing ~/.vlx setup
bun run src/cli.ts daemon

Source runs use the same ~/.vlx state home as the binary. The self-updater is inert from source (vlx update reports "running from source").

setup/install.sh (Linux/WSL2) still provisions a dev machine end-to-end — including a systemd unit for source installs — and setup/check-prereqs.sh verifies the toolchain.

---

Releases

Binaries are built and published automatically by the vlx-release Azure Pipeline on every push to main: it bumps the patch version off the last published release, cross-compiles all three targets, and uploads them plus latest.json to the public container (with a v<version>/ archive copy for rollback). Cutting a release = merging to main.

Local cross-compiling on Windows does not work (Bun cannot extract foreign-target runtimes there) — always release through the pipeline.

---

Optional overrides

Variable	Default	Description
VLX_HOME	~/.vlx	Operational root for config, state, secrets, and staged binaries
VLX_CONFIG	~/.vlx/vlx.yaml	Path to config file
VLX_DB_PATH	~/.vlx/state.db	Path to SQLite state database
VLX_UPDATE_URL	release channel	Override the self-update base URL
VLX_NO_UPDATE	unset	1 skips the on-start update check
LOG_LEVEL	info	Logging verbosity (trace / debug / info / warn / error / fatal)