Your terminal.
Your remote machines.

Install the small AHVM client on your Mac or Linux machine. Your sandboxes run on a Linux server you control. No domain or public API port is needed.

Review the community and commercial licensing terms before installation.

1. Install the client

curl -fsSL https://ahvm.app/install.sh | bash
export PATH="$HOME/.local/bin:$PATH"

# Or use Homebrew:
brew install mariobm/ahvm/ahvm

Clients are available for Apple Silicon, Intel Macs and Linux x86_64. The curl installer needs curl, gzip and Python 3, and installs to ~/.local/bin. Set AHVM_BIN_DIR to choose another directory. You can inspect the script before running it.

2. Connect your Linux server

ahvm host add home --ssh root@192.168.1.50 --install

# Existing SSH aliases work too:
ahvm host add home --ssh agent_house --install

Use one of these commands with your server's address or SSH alias. The host needs Linux x86_64, KVM, systemd, glibc 2.35 or newer, Python 3, OpenSSL 3 and GNU tar. Use root or an account with passwordless sudo. Installation fetches the server runtime from GitHub and the Ubuntu image directly from R2.

Leave off --install to register an already installed server. The first host becomes your default. SSH handles encryption and host-key checks; the admin token stays on the server and is not saved on your laptop.

ahvm host list
ahvm host use home
ahvm create dev --host home

3. Create a workspace

ahvm create dev --cpus 2 --memory 4096
ahvm exec dev -- bun --version
ahvm shell dev

# Or let AHVM generate a sandbox name:
ahvm create

Names identify sandboxes on the selected host. Ctrl-] detaches from an interactive shell without ending its session. Ubuntu includes Node.js LTS, Bun, Python, Git, build tools, Claude Code, Codex, OpenCode and Pi. Bring your own provider credentials. Inside the guest, run ahvm-dev to use the developer account.

4. Files and checkpoints

ahvm files put dev ./hello.txt /workspace/hello.txt
ahvm files get dev /workspace/hello.txt ./download.txt
ahvm snapshot create dev before-change
ahvm stop dev
ahvm start dev
ahvm delete dev

Uploads stream and replace the guest file only when complete. Stop saves a local disk and memory checkpoint. Idle-stop is automatic; wake is explicit. Crash recovery uses the latest checkpoint, so local snapshots are not a replacement for off-host backups.

Images

ahvm image available
ahvm image list
ahvm image pull ubuntu-dev
ahvm image default ubuntu-dev
ahvm create dev --image ubuntu-dev

These are AHVM VM disks, not Docker images. Downloads come from the signed image catalog and are cached on the selected server. AHVM checks signatures, expiry, checksums and image sizes before publishing a cache entry. Ubuntu is the automatic default. Image updates affect future sandboxes; existing filesystems and snapshots remain unchanged.

Upgrades

ahvm upgrade                 # Client installed with curl
brew upgrade ahvm            # Client installed with Homebrew
ahvm host upgrade home       # Explicit server upgrade

Client upgrades verify signed release metadata. Homebrew-owned installations use Homebrew. The server updater preserves configuration and the selected image, checks the restarted API, and restores the previous runtime and database if the candidate fails. Custom installation paths and state-format migrations require manual handling.

Interactive commands can show a cached new-version notice. Checks happen at most once daily without delaying your command. Set AHVM_NO_UPDATE_CHECK=1 to disable them; JSON output and scripts stay quiet.

Host maintenance and networking

The control API remains on 127.0.0.1:8080. Previews use a separate listener and still need their own HTTPS/wildcard-domain setup for remote access. Private TCP access requires explicit administrator grants in /etc/ahvm-rust/private-access.json.

The standard runtime, config and data paths are /opt/ahvm-rust, /etc/ahvm-rust and /var/lib/ahvm-rust. Image downloads are cached under /var/lib/ahvm-images. Inspect service logs with sudo journalctl -u ahvm-rust.

For installation directly on a server, use the server installer. Delete or stop sandboxes before uninstalling; stopping the daemon alone intentionally leaves its workers running. ahvm host remove home only removes a saved client connection.

AHVM remains an initial-release product for evaluation, not a production security sign-off for hostile multi-tenant workloads. It originated as a fork of Bhatti.