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 two tools at runtime — install them first:

Tool	Min version	Why
git	2.x	Clones the client repo, manages per-run worktrees, pushes PRs
claude-code CLI	latest	Runs the actor agent sessions (claude-agent-acp)

Install claude-code with npm install -g @anthropic-ai/claude-code (requires Node 20+ for npm itself), then run claude once to authenticate. 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. Download the binary

Grab the binary for your platform from the release channel and put it on your PATH:

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

# Windows (PowerShell)
mkdir "$env:USERPROFILE\.vlx\bin" -Force
curl.exe -L -o "$env:USERPROFILE\.vlx\bin\vlx.exe" https://saarthi.blob.core.windows.net/releases/vlx-windows-x64.exe
# then add %USERPROFILE%\.vlx\bin to your PATH

# macOS (Apple Silicon)
mkdir -p ~/.vlx/bin
curl -L -o ~/.vlx/bin/vlx https://saarthi.blob.core.windows.net/releases/vlx-darwin-arm64
chmod +x ~/.vlx/bin/vlx
export PATH="$HOME/.vlx/bin:$PATH"   # add to your shell profile

# Linux x64: same, with vlx-linux-x64

Verify:

vlx --version

---

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 vlx daemon start checks https://saarthi.blob.core.windows.net/releases/latest.json. If a newer version is published, the daemon downloads it, verifies the SHA-256 from the manifest, swaps the binary on disk, and restarts itself into the new version in the same terminal — no manual steps.

• vlx update — check and apply right now
• 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/	Staged binaries during self-update

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 claude-code:

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)