Windows Installation Guide
A single PowerShell script installs everything you need to run AgEnD on Windows — WSL 2 + Ubuntu, your chosen AI backend(s) (Kiro CLI, Claude Code, Antigravity, Codex), AgEnD itself, your Discord/Telegram bot, and auto-start on boot. Once it finishes, you just talk to your AI agents in Discord or Telegram — no app to keep open.
Open PowerShell (press Win+X → Terminal), paste this line and press Enter:
powershell -ExecutionPolicy ByPass -c "irm https://songsid.github.io/AgEnD/install.ps1 | iex"
To try the beta on a fresh install, run this in the same PowerShell window before the installation line above:
$env:AGEND_VERSION = 'beta'AGEND_VERSION accepts only beta, latest, or an exact version such as 2.3.2. Unset installs latest; elevation and reboot resume keep your choice. This does not switch an existing installation; use agend update --beta for that. Run Remove-Item Env:AGEND_VERSION to clear the choice for later fresh installs.
To skip the drive prompt for a new distro, set $env:AGEND_WSL_DRIVE = 'D:' before the one-liner. Only a local drive letter is accepted, and it must have at least 5 GB free. Elevation and reboot resume keep this choice. A saved planned location takes precedence on a retry; an existing distro is reused and is never moved by this setting. Clear it for later installs with Remove-Item Env:AGEND_WSL_DRIVE.
- • Windows asks once for Administrator approval, because the installer enables WSL. Choose Yes: the installer opens in a new window — in Windows Terminal when it is installed (it shows Chinese text properly), otherwise in a PowerShell window. The window you pasted into waits and says how it ended. Already in an Administrator PowerShell? It runs right there, or reopens in Windows Terminal when that's installed and you aren't in it.
$env:AGEND_INSTALL_TERMINAL = 'conhost'keeps the old console window. - •
-ExecutionPolicy ByPassapplies to that one command only. Your execution policy is not changed, and there is no file to unblock. - • If it asks you to restart Windows, press Enter: after you log back in, the install carries on by itself (Windows asks once for approval; choose Yes). If it doesn't, paste the same line again: it resumes where it stopped.
- • Every long step shows how long it has been running and how long it usually takes, with the tool's own progress under it.
- • Don't press Ctrl+C in that window: there it stops the program, it doesn't copy. (During an automatic step it asks first.) To copy, select the text with the mouse and right-click; to paste, right-click.
Prefer to download the script and run it yourself? See Manual install. On macOS or Linux, the one line is curl -fsSL https://songsid.github.io/AgEnD/install.sh | bash.
Prerequisites
- • Windows 11 (or Windows 10, version 2004+), 64-bit (x64 or ARM64)
- • Stable internet (~1–2 GB download)
- • At least 5 GB free disk space (SSD recommended)
- • BIOS virtualization (VT-x / AMD-V) enabled
- • An account for whichever AI backend you choose — e.g. a free AWS Builder ID for Kiro CLI, or an Anthropic / Google / OpenAI / xAI account for the others
- • A Discord or Telegram account
- • A Bot Token (Discord: Developer Portal; Telegram: BotFather) — or none at all: choose Web only (no bot) on the setup page and use AgEnD from its web dashboard
/start in the group. On Discord, it detects your account from a server message or DM and asks you to confirm it, with a required valid-ID fallback; it also asks for the General channel ID: see the Discord bot setup guide.What the installer does
Follow the on-screen prompts. The whole process takes about 10–20 minutes depending on your connection. The installer runs in 5 stages:
- [1/5] Install WSL 2 + Ubuntu — it installs Ubuntu-24.04. With two or more local drives that have at least 5 GB free, it asks where to install, shows free space and marks the recommended default (system drive with at least 20 GB free, otherwise the roomiest local drive); Enter accepts it. With one eligible drive it does not ask. The location is saved before installation and kept across retries and reboots. If you removed the previously installed distro, it clears that stale choice and lets you choose again. If you already have Ubuntu, it offers to install a separate Ubuntu just for AgEnD, named
AgEnD(recommended: your existing one is left untouched), or to use the existing one (its settings change, and it says how), or Enter to quit without changing anything. A later run reuses that AgEnD Linux; it never installs a third. A WSL that is already version 2 or later isn't updated again; an older one is updated through the Microsoft Store first, with GitHub only as a fallback (on a shared office network GitHub may refuse for a while, and the installer says so and goes on when the WSL you have is usable). A reboot may be required; after you log back in, it continues where it left off. - [2/5] Install AI backend(s) — pick one or more (comma-separated; just press Enter for Kiro CLI only; a resumed install shows your saved choice, and Enter keeps it). A backend that is already installed and answers
--versionis kept, with its version shown, and its installer is skipped:- Kiro CLI (free — AWS Builder ID / GitHub / Google)
- Claude Code (Anthropic account, Claude Pro $20/mo+)
- Antigravity CLI (free — Google account)
- OpenAI Codex (ChatGPT account or API key)
- [3/5] Install AgEnD — automatic (installs Node.js 22 LTS + tmux via the official installer).
- [4/5] Prepare browser sign-in — Kiro CLI, Claude Code and Codex sign in on the setup page in the next stage, in your browser: nothing to choose or paste in this window. Kiro asks for its account method there, Claude Code shows a code to paste into the page, and Codex shows a link and a device code. Sign in later on the page leaves a backend for the dashboard's Needs you. Antigravity keeps its console sign-in: the installer prints the command to run later. An older AgEnD package without browser sign-in uses the console sign-in instead.
- [5/5] Connect your bot & start — in your browser, not the console: the installer opens AgEnD's setup page and copies its setup code for you (paste it into the page with Ctrl+V). On the page, choose Discord or Telegram and paste your Bot Token (Verify shows whose bot it is), or choose Web only (no bot) to skip the bot and use the web dashboard alone (backend sign-ins are there too: Settings → Agents → Sign-ins); on Telegram, send
/startin your group so it finds the group; on Discord, confirm the account it detected and enter the General channel ID. When you finish, AgEnD starts and is installed as a service. The page lasts 15 minutes and counts down, warning in the last three. If it closes (time, inactivity or too many wrong codes), the installer says why: Enter reopens it (backends already signed in aren't asked again), orcswitches to the same setup in the console (agend quickstart), which is also offered when the page can't open. When the page asks for a confirmation on the host, the installer opens a separate window runningagend settings confirm, which lists exactly what will change and asks y/N; a person at the computer must answer it. At the end it opens the web dashboard for you (its one-time sign-in code copied, so you paste it with Ctrl+V) and puts two shortcuts on your desktop: AgEnD 儀表板 does the same any time later, and AgEnD 重新啟動 restarts AgEnD after asking first. Already have AgEnD on this PC (for example you update it withagend update)? Paste the same line again: it sees AgEnD is installed, asks whether to check or repair its setup and service or finish a backend sign-in (No by default; your settings are kept either way), and then offers to add or update the two shortcuts. It never redoes the setup. The console commands are listed under "Advanced", for when you need them.
Manual install
The same installer, without the one line: download install-agend.ps1 and run it yourself.
Place the script & open PowerShell as Administrator
Put install-agend.ps1 somewhere easy to find (Desktop, D:\Tools, …). Avoid paths with non-ASCII characters. Then open an Administrator PowerShell: search “PowerShell” → right-click → Run as administrator (or press Win+X → Terminal (Admin)).
Allow the script to run (first time only)
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned Unblock-File .\install-agend.ps1
Enter Y when prompted, then cd to where the script is (e.g. cd ~/Desktop).
Run it
.\install-agend.ps1
Follow the on-screen prompts: the same 5 stages as above.
.\install-agend.ps1 again, for a manual install) — it detects completed stages and resumes. To start completely from scratch, run $env:AGEND_INSTALL_FORCE = '1' first, then the one line, in the same PowerShell window. For a manual install, run .\install-agend.ps1 -Force.Auto-start on boot
The installer wires up three mechanisms so your bot is online after every reboot with zero manual steps. The second one needs the service from stage 5: answer yes when quickstart offers to install it. If that step was skipped or failed, run agend install inside WSL.
- 1. WSL starts on Windows login via
start-wsl.vbsin the Startup folder (%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup\). - 2. AgEnD starts inside WSL via a systemd service — whenever WSL is running, AgEnD runs.
- 3. WSL never idles out —
.wslconfigkeeps it alive, so closing the terminal window doesn't stop the service.
Everyday use
Normally you just chat with the bot in Discord/Telegram — nothing to open. If the bot ever stops responding, open PowerShell or CMD:
wsl # enter WSL (works regardless of install drive) agend ls # show all agent statuses agend start # start all agent services agend stop # stop all agent services agend attach <name> # open an agent's tmux screen agend update # update AgEnD to the latest version agend web --code # sign-in code for the web dashboard (localhost:19280) agend shortcuts # make or update the desktop shortcuts kiro-cli # open Kiro CLI manually exit # leave WSL
agend attach, press Ctrl+B, release, then D.Do not press Ctrl+C — it terminates the agent.FAQ
“This script must be run as Administrator”
Open PowerShell with right-click → Run as administrator.
“Cannot connect to the network”
The installer checks the sites it needs, from Windows and then from WSL, and names what failed: DNS, a timeout, a refused connection, an untrusted HTTPS certificate or a proxy, with what to do. A company network that inspects HTTPS needs its root certificate in Ubuntu (set NODE_EXTRA_CA_CERTS); a company proxy needs the Windows proxy set for WSL. When a required site can't be reached, the installer asks before going on, and stops by default.
Where is the install log?
Everything the installer shows also goes to a log in %LOCALAPPDATA%\AgEnD\install-logs (the last 10 are kept). Setup and sign-in codes, tokens and URL credentials are hidden before anything is written. When the installer stops, the window you pasted the command into says at which stage and where the file is: send that file when you ask for help.
It stopped because the install would belong to another account
WSL, AgEnD, the shortcuts and the resume after a restart all belong to the account the installer runs as. If a standard account approved the Administrator prompt with another administrator's password, the installer stops before changing anything and names both accounts. Ask IT to give your account administrator rights for the install, or sign in as the other account and install there.
WSL asked me to reboot after install
That's normal. Reboot, then run the script again — it resumes automatically.
A backend sign-in doesn't finish
On the setup page, cancel that sign-in and try again, or choose Sign in later: the backend then waits in the dashboard's Needs you, where you can sign it in once AgEnD is running.
Bot stopped replying after a reboot
It usually recovers on its own within 30–60 seconds. If there's still no response after 2 minutes:
wsl -u root -- bash -lc "agend start"
Antivirus blocks the .vbs startup script
Ask your IT team to whitelist %APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup\start-wsl.vbs, or start manually (run wsl once after boot).
BIOS virtualization isn't enabled
Reboot into BIOS setup (usually F2 / Del / F12) and enable Intel VT-x or AMD-V (SVM Mode).
How do I update AgEnD?
Send /update in General, or enter WSL and run agend update. Installed before the desktop shortcuts existed? In WSL, run agend shortcuts to make “AgEnD 儀表板” and “AgEnD 重新啟動” (or paste the one-liner again: on a PC that already has AgEnD it offers a check or repair first, then the shortcuts). If agend itself stopped working (agend: command not found after an interrupted update), paste the one-liner again: it repairs AgEnD in place and keeps your settings and data.
Complete removal
Run these in PowerShell, in order:
wsl --unregister Ubuntu-24.04 Remove-Item "$env:USERPROFILE\.agend-install-progress" -ErrorAction SilentlyContinue Remove-Item "$env:APPDATA\Microsoft\Windows\Start Menu\Programs\Startup\start-wsl.vbs" -ErrorAction SilentlyContinue
The installer merged two keys into your %USERPROFILE%\.wslconfig ([wsl2] vmIdleTimeout=-1 and [general] instanceIdleTimeout=-1) and kept your other settings, with a backup next to it (.wslconfig.agend-backup-…). Remove just those two lines, or restore the backup; don't delete the file if it holds settings of your own.
To remove the WSL feature itself: Settings → Apps → Optional features and turn off Windows Subsystem for Linux.