Skip to content

installation.md

Latest commit

 

History

History
223 lines (169 loc) · 8.85 KB

installation.md

File metadata and controls

223 lines (169 loc) · 8.85 KB
Raw

Install A3S Box

A3S Box provides one installer contract through native launchers for each host:

  • install.sh for Linux and macOS, without requiring PowerShell; and
  • install.ps1 for Windows, without requiring Bash.

Both launchers detect the host, resolve a GitHub release, verify its SHA-256 digest before extraction, validate the package layout and reported version, then replace a previous installer-managed copy as one staged operation.

Supported release targets

Host Architecture Release target
Linux x86_64 linux-x86_64
Linux arm64 linux-arm64
macOS Apple Silicon macos-arm64
Windows x86_64 windows-x86_64

Intel macOS and Windows on ARM are rejected rather than receiving an incompatible archive. The installer installs the runtime distribution; it does not enable KVM, HVF, WHPX, or Linux Sandbox host capabilities by itself. Review Platform boundaries and the Windows WHPX guide before running real workloads. For Sandbox, complete Linux Sandbox host preparation after install.

One-line installation

Linux or macOS:

curl --proto '=https' --tlsv1.2 -fsSL \
  https://raw.githubusercontent.com/A3S-Lab/Box/main/install.sh | sh

Windows PowerShell 5.1 or newer:

irm https://raw.githubusercontent.com/A3S-Lab/Box/main/install.ps1 | iex

Open a new terminal if the current one does not see the updated PATH, then verify the result:

a3s-box --version
a3s-box info

Piping code from the network executes the current main branch. To inspect it first, download install.sh or install.ps1, review the file, and invoke it locally.

Homebrew remains available on Linux and macOS:

brew install a3s-lab/tap/a3s-box

Version and destination controls

The default destinations are:

  • ${XDG_DATA_HOME}/a3s-box when XDG_DATA_HOME is set;
  • $HOME/.local/share/a3s-box on other Linux and macOS hosts; and
  • %LOCALAPPDATA%\Programs\A3S Box on Windows.

The release stays self-contained at that location so its sibling libraries and guest executable are not separated from a3s-box.

Behavior Linux/macOS Windows
Pin a release --version v3.3.0 -Version v3.3.0
Choose destination --install-dir PATH -InstallDir PATH
Do not change PATH --no-modify-path -NoModifyPath
Replace an unmanaged directory --force -Force
Install a local package --archive FILE --sha256 HEX -ArchivePath FILE -Sha256 HEX

Pass Unix options after sh -s -- when using a pipe:

curl --proto '=https' --tlsv1.2 -fsSL \
  https://raw.githubusercontent.com/A3S-Lab/Box/main/install.sh |
  sh -s -- --version v3.3.0 --no-modify-path

Invoke the downloaded PowerShell text as a script block when options are needed:

$installer = irm https://raw.githubusercontent.com/A3S-Lab/Box/main/install.ps1
& ([scriptblock]::Create($installer)) -Version v3.3.0 -NoModifyPath

The corresponding environment variables are A3S_BOX_VERSION, A3S_BOX_INSTALL_DIR, A3S_BOX_ARCHIVE, and A3S_BOX_SHA256. Unix also supports A3S_BOX_PROFILE or --profile to select the shell startup file. Set A3S_BOX_NO_MODIFY_PATH=true to suppress PATH changes in a piped invocation. Set GITHUB_TOKEN when authenticated GitHub API access is needed because of rate limits.

Linux Sandbox host preparation

The installer does not enable Sandbox host capabilities. On a certified Linux host, after installing Box and locating the pinned a3s-oci binary:

sudo bash /path/to/box/scripts/prepare-linux-sandbox-host.sh \
  --install-launcher /absolute/path/to/a3s-oci
export A3S_BOX_SANDBOX_DELEGATED_CGROUP_ROOT=...  # printed by the script
a3s-box run --rm --isolation sandbox alpine:3.20 -- sleep 5

The script:

  • prepares a delegated cgroup v2 tree owned by the invoking non-root identity;
  • ensures subordinate UID/GID ranges and userns-related sysctls when needed; and
  • installs the setuid launcher at /usr/local/libexec/a3s-box-sandbox-oci-launcher when --install-launcher is supplied (required on production hosts; discovery also checks env and packaged paths).

A mode 4755 launcher elevates effective uid only. The operator's real gid and supplementary groups stay until a3s-oci adopts effective gid 0, clears groups, and migrates into the Box-created child under the delegated root while it is still effective uid 0. The unprivileged parent does not need write access to the cgroup v2 common ancestor. Do not install mode 6755 or a separate wrapper for that identity: the in-process adopt path is the product contract. A Linux tip proof that the documented steps start a Sandbox is still required before claiming the operator path closed.

Do not set A3S_BOX_OCI_MIGRATION for the Sandbox GA default. Use A3S_BOX_OCI_MIGRATION=off only for MicroVM-only hosts without OCI prep.

CI qualification uses prepare-linux-sandbox-ci-host.sh (setpriv on nosuid runners) and is not a substitute for the operator setuid install. Evidence: Sandbox GA evidence. On a suid-capable host, prove the operator path with scripts/proof-linux-sandbox-setuid-launcher.sh (non-root run, setpriv unset). Non-root Host spawn without A3S_BOX_CI_SETPRIV_WRAPPER now fail-closes unless the resolved launcher is root-owned mode 4755.

Linux / WSL MicroVM :ro volumes

MicroVM -v host:guest:ro on Linux and WSL host-enforces write denial via a private MS_RDONLY bind alias before virtio-fs attach. That path needs host CAP_SYS_ADMIN (typically root). Without it, Box fails closed before durable boot with a CAP_SYS_ADMIN hint — it does not fall back to guest-honor-only :ro.

The Sandbox setuid launcher above elevates SandboxViaOci only; it does not cover MicroVM RO staging. On WSL, run MicroVM :ro workloads as root (or an equivalent capability-bearing identity), or omit :ro and use a writable bind.

Windows/WHPX MicroVM :ro uses BindFlt instead and does not need Linux CAP_SYS_ADMIN. See Windows WHPX.

Tip (writable bind + named volume on WSL, no :ro): host marker write-through and volume persist across two run --rm passed on tip (wsl_rw_tip=pass). Does not claim Enterprise GA.

Tip (Windows WHPX writable bind truncate): after libkrun 5302041, guest printf short > host-file truncates correctly (win_otrunc_bind_tip=pass). Does not claim Enterprise GA or Linux UID/GID storage on Windows binds.

Tip (MicroVM egress on WSL Bridge / passt_bridge): default profile denies link-local metadata; first-match --egress deny:1.1.1.1/32 denies that IP while a control run without deny fetches public HTTP (wsl_microvm_egress_tip=pass). Keep-authority Sandbox Bridge now installs the same packet-field FORWARD filter on Linux (unit-proven); WSL tip-prove still needs interactive sudo on this host. Does not claim Sandbox≈MicroVM or Enterprise GA.

Offline installation

An offline install must supply the release tag and a trusted SHA-256 value. The archive must retain its published root directory and target-specific layout.

Linux or macOS:

sh ./install.sh \
  --version v3.3.0 \
  --archive ./a3s-box-v3.3.0-linux-x86_64.tar.gz \
  --sha256 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

Windows:

.\install.ps1 `
  -Version v3.3.0 `
  -ArchivePath .\a3s-box-v3.3.0-windows-x86_64.zip `
  -Sha256 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

Replace the example digest with the value published for that release. The online path reads the digest from GitHub release metadata and falls back to the asset's .sha256 manifest. It never installs a download that lacks a valid digest.

Upgrade and ownership behavior

Every successful install writes .a3s-box-install.json inside the destination. A later run may replace a directory carrying that marker. A non-empty directory without the marker is left untouched unless --force or -Force is explicit. Force never permits replacing a filesystem root, user-profile root, or known system directory.

The new package is copied to a sibling staging directory and its executable is checked before activation. If activation or the final version check fails, the previous managed directory is restored.

On Unix, the installer manages one marked block in the selected shell profile. On Windows, it adds the installation directory to the per-user PATH without using setx, so an existing long PATH is not truncated.

Uninstall

Delete the exact installation directory shown by the installer. On Unix, remove the block between # >>> a3s-box installer >>> and # <<< a3s-box installer <<< from the shell profile it reported. On Windows, remove that same installation directory from the user PATH. Runtime state stored elsewhere is intentionally not deleted by uninstalling the binaries.