2. Download, run and system requirements
[!ref] New-user tutorial: a step-by-step walk-through of installing and signing in for the first time is in the Quick Start Guide, "Install and sign in"; this chapter gives the complete per-platform story of system requirements, download and how to run.
2.1 System requirements
| Category | Requirement |
|---|---|
| Operating system | Windows 10 (1809) or later; macOS 12.0 Monterey or later; mainstream Linux (Ubuntu 22.04 / Debian 12 / CentOS Stream 9 or newer) |
| Domestic OS | Kylin desktop V10 SP1 (Kylin-Desktop-V10-SP1-2503); UOS V20 (Uos-Desktop-V20-1060); Kylin ARM64 (separate builds for V10 SP1 and V11) |
| CPU architecture | x86-64 (64-bit); macOS also supports Apple Silicon (arm64); domestic platforms additionally have ARM64 (aarch64) builds |
| Runtime dependency | Windows: built-in WebView2 runtime; Linux: webkit2gtk (4.0 / 4.1 — pick the matching build for your distro); macOS: system WebKit, nothing to install. The Linux DEB packages ship a relocatable WebKit 4.1 runtime of their own, so they run even where no suitable webkit2gtk-4.1 is available; when the target machine already has one, the system library is used automatically (see §27.1) |
| RAM | 8 GB minimum, 16 GB recommended |
| Disk | 1 GB free minimum, 2 GB+ recommended (local sessions / skills / logs / code index) |
| Display | 1280 × 720 or higher recommended |
| Network | Internet required on first launch to fetch the model list; day-to-day access to the account service and your chosen model provider (offline-capable features are noted in their chapters) |
2.2 Download and run (install-free)
AVL Code is install-free — download and run, with no installer wizard. From the official download page www.avlcode.cn/#download, pick the build for your platform and run it directly (the beta uses the alpha channel — each platform link always points to the latest build):
| Platform / build | How to run |
|---|---|
| Windows x64 | Download and double-click to run (install-free, no wizard) |
| macOS Universal | Intel and Apple Silicon; drag into Applications and run |
| macOS Apple Silicon (arm64) | Apple Silicon only, smaller; drag into Applications and run |
| Linux x64 | Unpack and run directly |
| Linux AppImage | single-file, no install — chmod +x and run |
| Linux Snap | Snap package (snap install) |
| Linux WebKit 4.1 | newer distros (needs webkit2gtk-4.1) |
| Kylin V10 SP1 | dedicated domestic build (Kylin-Desktop-V10-SP1-2503, x86) |
| UOS V20 | dedicated domestic build (Uos-Desktop-V20-1060) |
| Kylin ARM64 (archive) | domestic ARM64 (aarch64) install-free build; unpack and run |
| Kylin V10 ARM64 (DEB) | domestic ARM64 installer (avlcode_v10_<version>_arm64.deb) with a bundled WebKit 4.1 runtime |
- Windows / Linux: download and run — no installation.
- macOS: it's best to drag the app into Applications before running — otherwise, running from "Downloads" / "Desktop", "check for updates" gets locked by macOS App Translocation (see §27.7.2).
- Domestic environments: dedicated builds for Kylin V10 SP1 and UOS V20; ARM64 (aarch64) machines have their own domestic ARM64 channel (archive + V10 DEB), and update checks follow that separate channel rather than sharing the x86 one.
- Linux Wayland sessions: under Wayland the window keeps the app's own frameless chrome instead of falling back to a system title bar.
Docs: www.avlcode.cn/docs (User Manual / Quick Start / Reference).
On first launch the app does a brief local initialisation; the process is transparent to the user.
2.3 First launch
After launch you see three main areas:
- Left sidebar: workspace list + sign-in entry + Settings entry.
- Center session area: session tabs + message stream + input box.
- Right floats (on demand): plan / todo, assistant configuration, approval dialogs, etc.
Setup wizard: on every launch, as long as no model is usable (for example you haven't signed in yet and the built-in AVL-Zero has no key), a three-step wizard opens automatically:
| Step | What it does |
|---|---|
| 1. Sign in | Phone-number sign-in (an unregistered number gets an account automatically); if you're already signed in it shows the current account and available points, with "Next" or "Switch account / sign in again". If you already have your own model service, click "Configure manually": the wizard steps aside and opens Settings → Models → Providers, and closing Settings brings you back to step 2 |
| 2. Create project / Open project | When you have previous projects it lists "Open a previous project" by default; you can also pick "New project" (name defaults to Project_NN, location prefers the folder you used for your last new project) or "Connect to a remote server (SSH)" |
| 3. Start chatting | Offers a few examples plus "Type my own"; clicking an example only fills the text into the input box — it is not sent automatically |
- The × in the top-right corner (or {{kbd:Esc}}) is "Skip setup"; step 1 offers "Skip this step" and step 2 "Maybe later". Dismissing it only applies to this launch — if the problem isn't solved, it opens again next launch.
- To run it again: "Run setup wizard" in the "Setup wizard" block at the bottom of Settings → Account, or "Run setup wizard" in the command palette.
- Windows location: defaults to the last fixed local drive, automatically excluding removable media such as USB sticks, external drives, card readers and network drives, as well as drives that are BitLocker-locked or not ready. When the drive holding a project is BitLocker-locked, its entry in the list is greyed out and tagged "Locked by BitLocker" — one click brings up the system unlock dialog, and the project opens automatically once unlocked; a drive tagged "Drive not ready" can't be opened for now.
If you'd rather not use the wizard, just click the Sign in button in the lower left to bind your account (see Chapter 3). You can also use it without signing in by entering an API key under Settings → Models → Providers.
2.4 Command-line entry points (advanced)
In addition to the desktop app, AVL Code also ships a set of command-line entry points for users who want to script things or work on remote servers. The CLI shares sessions and config with the desktop app; the two can hand work back and forth. The CLI getting-started info and subcommand list live under Settings → Data → Command-line tools.
The TUI subcommands built into the main binary (no extra install required):
| Command | Purpose |
|---|---|
AVLCode tui |
Launch the TUI version in your terminal, sharing sessions with the desktop |
AVLCode zagent-tui |
Launch the batch-mode conversation TUI, useful for scripting |
The terminal build now shares one data store with the desktop app, and has everything you'd expect day to day:
- Sessions are written straight into the desktop app's session store — a conversation you run in the terminal is there when you go back to the desktop.
/sessionslists recent sessions,/resume <session ID>switches to one, {{kbd:F2}} starts a new one, and-session <ID>at launch resumes a specific session. - Context compaction (
/compact) and session goals (/goal) share their source of truth with the desktop app; the compaction snapshot travels with the session. - Sign-in and account:
/login(username + password, or/login phone <number>for an SMS code),/sso,/logout,/usagefor usage,/redeem <code>,/feedback <text>; a startup announcement banner is shown on launch. - Hooks and approvals: workspace-level hooks apply, and approvals are decided inline in the terminal —
yallow once /aallow always /ndeny (Esc=n, auto-denied after 30 seconds). "Allow always" is written to the workspace approvals file and is recognised by the desktop app too. - Sandbox attachments:
/attach <path> [ro|rw]attaches a directory or file outside the workspace to this session (read-only by default),/attachwith no arguments lists the current set, and/detach <path>removes one. - The terminal build starts the toolchain it needs by itself and reclaims it on exit; status is shown in the bottom status bar.
[!ref] The complete command list and arguments: see the Reference Manual, "Command-line entry points".