Windows: WSL → Ubuntu → AgentFEM

For an AI assistant: complete the permitted work yourself. Show the user only the next action that needs their approval. No GitHub clone, Windows Python, Docker or AgentFEM installer scripts are required. Already have working Ubuntu/WSL2? Skip platform installation and reuse it.

国内用户：先准备 WSL，再从清华镜像导入 Ubuntu，最后镜像安装 AgentFEM。 不用先克隆 GitHub，不用默认打开“Windows 功能”逐项勾选；让智能体完成允许的操作。

One prompt, one visible next step

Start with three visible stages: 1/3 WSL → 2/3 Ubuntu and account → 3/3 AgentFEM. Mark already working stages complete. Do not promise a duration or a percentage while a download is running. After each stage, say what is complete, what remains, and whether the user needs to act.

For example: “WSL is ready (1/3). Next I will prepare Ubuntu and your working account. No action needed.” At completion: “AgentFEM is ready (3/3). Would you like to try a small example?” Installation is complete without that example.

中文交接示例：“第 1/3 步：WSL 已准备好。接下来我会安装 Ubuntu 并配置工作账户， 你暂时不用操作。”只有需要提权、重启或本地密码输入时，才交给用户。 不要把智能体能执行的下载、校验、账户配置和检查，变成用户的复制粘贴任务。

The web prompt and installation.onboarding in agentfem.json share this flow. Reuse working stages and retain the user's chosen channel. If a stage fails, keep its error and show one next action; resume after that blocker is resolved. If the agent cannot execute commands, give the same manual path directly.

Show a short status such as WSL: needs approval — open Terminal (Administrator) or Environment: installing — no action needed. Do not dump raw diagnostics unless asked; keep the exact error for troubleshooting. Ask for Windows approval only when the operation requires it.

1. Prepare WSL only if needed

Inspect wsl --status and wsl --list --verbose in PowerShell. A blocked command is a permission issue, not proof that WSL is missing. A Store Ubuntu App is not yet a registered distribution: check the WSL inventory.

If WSL is missing, use approved elevation. If the agent cannot obtain it, give just this handoff: “Open Terminal (Administrator), run the following command, and restart only if Windows asks.”

wsl --install --no-distribution --web-download

This deliberately installs the platform without downloading Ubuntu. --web-download is an alternative to the Store, not a domestic mirror or a speed guarantee. If its download fails, an approved Store route is wsl --install --no-distribution. Do not switch routes after denied consent or a restart request. Do not start with the Windows Features GUI; reserve manual component/firmware repair for a specific diagnosed failure.

If the kernel update is missing

Distinguish an older inbox WSL missing its WSL2 kernel update from a modern WSL installation needing an update. Inspect the actual error and host architecture first. For modern WSL, try wsl --update --web-download when permitted. Do not send every user a legacy kernel installer.

If automatic download fails, offer one browser handoff with the exact architecture-matched Microsoft link, expected filename and installation action. Use Microsoft's manual installation page, step 4 for the legacy kernel package, or the official WSL release route for modern WSL. Check the current download size before describing it as small; do not invent a size or speed guarantee. Keep publisher/signature checks in the agent's work.

Suggested handoff: “WSL needs its kernel update. Automatic download failed. Open this Microsoft download link, save the installer, then double-click it and approve the Microsoft installer. Tell me when it finishes; I will check it and continue. You do not need to reinstall Ubuntu.” Present the actual verified link, not instructions to search for a package. Resume from this stage.

2. Add Ubuntu from the mirror, only if absent

For the standard Microsoft route, wsl --install -d Ubuntu installs Ubuntu; complete its first-launch account setup locally. For a requested mirror route, use the image recipe below instead. Choose one route, not both.

For a requested mainland/mirror route, use the verified Ubuntu image import below directly. Do not first loop through Store, winget and wsl --install -d Ubuntu after a distribution-metadata timeout. Importing a local image avoids that metadata download; it does not bypass permissions.

Copy-safe x64 mirror recipe (PowerShell)

Agent execution reference, not a novice copy-and-paste task. The agent should execute and check each stage itself. If command execution is unavailable, provide only the next short command block in the correct shell, with resolved paths and filenames. Keep download, verification and import separate; wait for each outcome before showing the next block. Do not give two download commands and imply installation is complete, or remove checksum validation to shorten the instructions. Explain success in ordinary language after checking it.

Keep the full recipe collapsed when reading this page:

Agent reference: verified Ubuntu download and import

For a new distribution only. Reuse an existing compatible one instead of running this block. It uses a user-owned directory, checks every native command, and verifies the exact image against the mirror's published manifest. It does not overwrite a registered distribution or an existing destination.

$ErrorActionPreference = 'Stop'
$afmDistro = 'Ubuntu-24.04'
$afmTarget = Join-Path $env:LOCALAPPDATA 'AgentFEM\WSL\Ubuntu-24.04'
$afmArch = $env:PROCESSOR_ARCHITEW6432
if (-not $afmArch) { $afmArch = $env:PROCESSOR_ARCHITECTURE }
if ($afmArch -ne 'AMD64') { throw 'This recipe is x64 only; select a verified image for your architecture.' }
$afmExisting = @(wsl.exe --list --quiet)
if ($LASTEXITCODE -ne 0) { throw 'Check WSL readiness/permission before importing.' }
$afmExisting = @($afmExisting | ForEach-Object { ($_ -replace "`0", '').Trim() })
if (($afmExisting -contains $afmDistro) -or (Test-Path -LiteralPath $afmTarget)) {
    throw 'Existing distribution or directory: inspect and reuse; do not overwrite.'
}
$afmDownload = Join-Path $env:TEMP ('agentfem-ubuntu-' + [guid]::NewGuid().ToString('N'))
New-Item -ItemType Directory -Path $afmDownload | Out-Null
$afmBase = 'https://mirrors.tuna.tsinghua.edu.cn/ubuntu-releases/24.04'
$afmSums = Join-Path $afmDownload 'SHA256SUMS'
curl.exe -fL --retry 2 --connect-timeout 20 -o $afmSums "$afmBase/SHA256SUMS"
if ($LASTEXITCODE -ne 0) { throw 'Ubuntu checksum download failed.' }
$afmEntries = @(Get-Content -LiteralPath $afmSums | Select-String '^([0-9a-fA-F]{64})\s+\*?(ubuntu-24\.04(?:\.\d+)?-wsl-amd64\.wsl)$')
if ($afmEntries.Count -ne 1) { throw 'Expected one Ubuntu 24.04 x64 WSL image; inspect the published manifest.' }
$afmMatch = $afmEntries[0].Matches[0]
$afmFile = $afmMatch.Groups[2].Value
$afmImage = Join-Path $afmDownload $afmFile
curl.exe -fL --retry 2 --connect-timeout 20 -o $afmImage "$afmBase/$afmFile"
if ($LASTEXITCODE -ne 0) { throw 'Ubuntu image download failed; do not import it.' }
if ((Get-FileHash -LiteralPath $afmImage -Algorithm SHA256).Hash -ne $afmMatch.Groups[1].Value) {
    throw 'Ubuntu checksum mismatch; do not import.'
}
New-Item -ItemType Directory -Force -Path (Split-Path $afmTarget) | Out-Null
wsl.exe --import $afmDistro $afmTarget $afmImage --version 2
if ($LASTEXITCODE -ne 0) { throw 'Import failed; retain the image and error for diagnosis.' }
wsl.exe --list --verbose
if ($LASTEXITCODE -ne 0) { throw 'Cannot verify distribution inventory.' }

Retain the downloaded manifest, filename and digest. This checks integrity against the selected HTTPS mirror, not independent signature authentication. If policy requires upstream authenticity, also verify Ubuntu's signed `SHA256SUMS.gpg` against a trusted Ubuntu signing key before import. Never skip a failed checksum. The 24.04 directory tracks its maintenance release; do not guess a filename or use a desktop ISO. See the [TUNA image directory](https://mirrors.tuna.tsinghua.edu.cn/ubuntu-releases/24.04/).

Account: automate setup, not a shared password

Imported distributions normally start as root. This is useful for initial setup, not a reason to run the solver as root. With permission to prepare this new distribution, the agent can create a normal account without asking the user to choose a password:

Do this as part of the requested setup when permitted; do not ask a novice to paste account-management commands. First check for an existing ordinary user and reuse it. Explain that the proposed afm name is a local working account, not a registration or online identity. Honour a requested name instead.

wsl.exe -d Ubuntu-24.04 -u root -- useradd --create-home --shell /bin/bash afm
if ($LASTEXITCODE -ne 0) { throw 'Account creation failed; inspect existing users before retrying.' }
wsl.exe -d Ubuntu-24.04 -u afm --cd ~

Use this only for the newly imported distribution; reuse existing users. The new account has password login locked, not an empty/shared password, and is not granted passwordless sudo. Use explicit -u afm for subsequent agent calls (or preserve other settings when configuring [user] default=afm in /etc/wsl.conf). System administration remains separately authorised. Imported distributions do not use ubuntu.exe config --default-user. Store/bundle OOBE is a different route: if it asks for a password, the user enters it privately, never in chat.

3. Install the environment and confirm readiness

Inside Ubuntu as the ordinary user, reuse working Linux Miniforge. Otherwise use its TUNA release mirror or official distribution. Select a versioned Linux installer matching the architecture and its matching .sha256 file; verify before executing. The mirror's moving LatestRelease directory may change: missing files/checksum mean stop and reselect the published pair, not execute an unchecked download.

Example verified-release pair available on 2026-10-26, for a new x64 install. Run as one Bash block; no root, shell-profile edits or existing-prefix overwrite:

(
  set -eu
  test "$(id -u)" -ne 0
  test "$(uname -m)" = x86_64
  test ! -e "$HOME/miniforge3"
  afm_download=$(mktemp -d)
  cd "$afm_download"
  afm_base=https://mirrors.tuna.tsinghua.edu.cn/github-release/conda-forge/miniforge/LatestRelease
  afm_file=Miniforge3-26.9.4-0-Linux-x86_64.sh
  curl -fL --retry 2 --connect-timeout 20 -O "$afm_base/$afm_file"
  curl -fL --retry 2 --connect-timeout 20 -O "$afm_base/$afm_file.sha256"
  sha256sum --check "$afm_file.sha256"
  bash "$afm_file" -b -p "$HOME/miniforge3"
)

Then use INSTALL.md's mirror command. Use ~/miniforge3/bin/mamba if it is not on PATH. In agent tools use mamba run -n agentfem-env ... for each command; activation does not persist across tool calls. Query the selected mirror for a required version: an older package passing a basic solve does not satisfy a project's newer API needs.

Finish with agentfem doctor and agentfem workspace --protect. Report the installed version, environment location and readiness, then stop. Ask whether the user wants to try a small example. Create and run it only if requested; do not append benchmarks or performance tuning to installation.

Agent handoffs: one sentence, only when needed

Actual blocker	Tell the user
Host blocks WSL	“Please approve this WSL operation in your agent, or run the displayed command in your own terminal.”
Elevation unavailable	“Open Terminal (Administrator) and run the platform command above.”
Windows requests restart	“Save your work and restart; I will continue from the installed state.”
Store/bundle asks for credentials	“Enter your Linux account details in the local window, not here.”

Do not ask users to disable security controls, retry blocked tools through another shell, reinstall healthy WSL, or enable every Windows feature. After interruption inspect what already exists; do not duplicate downloads, imports or package transactions. To avoid PowerShell/Bash quoting errors, send complex Linux operations as an inspected LF .sh file, rather than nested interpolated command strings.

Keep the chosen mirror on later visits

Record the user's selected channel, environment path and installed version in the local project/agent handoff note; do not record credentials. Read it on later visits and keep using that channel for optional packages unless the user changes it. Use explicit per-command conda/pip sources; do not rewrite global configuration or mix compiled package channels. No new mirror CLI is needed. Additional package examples.

Other routes and evidence

If the user already has a compatible published Complete Runtime ZIP, use its installer instead; do not also install Ubuntu/Miniforge. Source/bundle helpers and detailed recovery records are optional tooling, not prerequisites. No repository clone is needed for any step above.

The 2026-10-26 field feedback reports Ubuntu mirror download around one minute, environment creation around 2.5 minutes, AgentFEM 0.4.1 and a completed static-solid solve. These are user-reported measurements, not timing guarantees or a validation of the current release. It used root; our recommended non-root preparation above is a deliberate safety improvement, not a claim that the reporter tested it.

Sources: Microsoft installation, WSL commands, imported distributions.