Get started

Install the CLI. Connect to AHVM Cloud or a Linux server you control. Create a persistent machine for your code.

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 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. Choose your connection

AHVM Cloud

Use your Cloud account to authenticate, then select Cloud as your connection. Your machines run on AHVM Cloud.

ahvm login
ahvm use cloud

ahvm login selects Cloud only when no default exists. Use ahvm use cloud to switch an existing default. Learn how saved connections work →

Your own Linux server

Your sandboxes run on a Linux server you control. No domain or public API port is needed.

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 use home

3. Create a workspace

On AHVM Cloud

After selecting Cloud, create a VM with the administrator-managed resource size:

ahvm create dev

Cloud users cannot override CPU or RAM. See the Cloud resource defaults →

On your own server

On a self-hosted connection, choose your CPU and memory size:

ahvm create dev --cpus 2 --memory 4096
# Bash opens inside the VM:
bun --version
exit

# Back on your computer, open another shell:
ahvm shell dev

Interactive ahvm create automatically opens Bash. Omit the name to generate one. Use ahvm create dev --no-shell to return after creation. --json and redirected stdin or stdout never open a shell, preserving scripted use. This also applies to ahvm --context cloud create dev. Names identify sandboxes on the selected host.

With CLI v0.3.6 and the updated Ubuntu development image, Bash opens as the ahvm user in /workspace, with a colored prompt. Use sudo for administration. Existing VM disks are unchanged; older images retain their previous shell user. Type exit to end the shell and return to your terminal; the VM keeps running. Ctrl-] detaches without ending the session.

Ubuntu includes Node.js LTS, Bun, Python, Git, build tools, Claude Code, Codex, OpenCode 2.0.18 and Pi. Bring your own provider credentials. For automated commands as the same user, use ahvm exec dev -- ahvm-dev COMMAND. The guest agent and direct API exec remain privileged for system operations.

See resource and lifecycle defaults →

Connections

Choose where commands run, and switch between Cloud and your own hosts.

Saved connections

CLI v0.3.7 and newer use a saved default connection. Run ahvm login for Cloud authentication; it selects Cloud only when no default exists. Run ahvm use cloud or ahvm use home to switch. Existing saved host defaults are preserved. ahvm context shows the current connection and ahvm contexts lists your choices.

ahvm use cloud
ahvm create dev
ahvm shell dev
ahvm --context home list

--context overrides the destination for one command. Names belong to that connection; AHVM never searches other hosts. Without a default, interactive commands ask you to choose and scripts fail with setup instructions. Advanced --endpoint connections use self-hosted credentials, never your Cloud login. Older clients can keep using --cloud and --host until upgraded.

Workspace defaults

Understand resource sizes, resident pause, and full stop before running a workload.

CPU, memory and disk

Self-hosted VMs use local storage and the server's selected image, initially ubuntu-dev. No R2 or S3 account is needed. The CLI defaults to 1 vCPU and 2048 MiB RAM for ordinary VMs, 2 vCPUs and 4096 MiB for Ubuntu desktop, and 4 vCPUs and 8192 MiB for Omarchy desktop. Use --cpus and --memory to choose different sizes. Direct daemon API create requests default to 1 vCPU and 2048 MiB regardless of image.

Ordinary AHVM Cloud VMs use an administrator-controlled size, initially 1 vCPU and 2048 MiB (2 GiB). Cloud users cannot override CPU or RAM; use ahvm --context cloud create dev. Administrators can change the size for new VMs under Cloud VM size in the dashboard. Workspace quotas and host capacity still apply. Existing VMs keep their size. Sizing flags remain available for self-hosted VMs.

Disk capacity comes from the selected image. The opt-in Cloud Omarchy desktop profile is fixed at 2 vCPUs, 8192 MiB RAM and a 40-GiB logical disk, independently of the ordinary Cloud size form.

Pause and idle stop

Ordinary VMs pause after 30 seconds without guest activity, keeping RAM and disk resident for fast resume. Operators can set AHVM_PAUSE_SECS (0 disables pause; otherwise 5–86400 seconds); Cloud administrators can change the host policy in the dashboard. Saved admin settings persist across restart and override the environment default.

The daemon stops ordinary idle VMs after one hour; AHVM_IDLE_SECS controls that separate timeout.

For VMs used by managed jobs, a full stop defaults to 300 seconds (five minutes) after completion and guest inactivity. Cloud administrators can change Managed-agent idle stop in the dashboard from 60 to 86400 seconds; it cannot be disabled. Active managed jobs and connected CLI shells prevent idle pause and stop. Later guest activity restarts the countdown.

A full stop releases resident RAM and keeps the VM and its disk; it never deletes the machine. The 30-second resident pause policy is independent. Older hosts keep the pause control but require an upgrade to expose the managed-agent setting.

Sweeps use AHVM_SWEEP_SECS, capped at five seconds. Active operations and connected shells defer idle stop, including a quiet shell waiting for an agent. After the last shell disconnects, the idle timer starts again.

Guest commands resume resident-paused VMs automatically, including self-hosted VMs. After a full self-hosted stop, use ahvm start dev.

Pause does not free RAM or create a backup. Detached background jobs alone do not prevent pause; desktop pause is not enabled yet. Replicated Cloud VMs wake automatically for exec, file operations and opening a new shell.

Files & checkpoints

Move files into a workspace, save checkpoints, and manage its lifecycle.

Files and lifecycle commands

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. With default local storage, stop saves a disk and memory checkpoint for ordinary VMs; desktop VMs use disk-only stop/start. With local storage, resume from resident pause is automatic; start after a full stop is explicit. Crash recovery uses the latest checkpoint, so local snapshots are not a replacement for off-host backups.

Replicated storage

Optional remote disk durability for operator-configured hosts. Requires v0.3.0 or newer.

Storage commands

The following commands require AHVM v0.3.0 or newer and a daemon advertising replicated-storage-v1; older releases do not provide them. The CLI checks server support before sending an explicit storage choice. Local storage remains the self-hosted default.

ahvm create dev --storage local --no-shell
ahvm storage status dev

# Experimental: only on an operator-configured Linux volume-service host.
ahvm create durable-dev --storage replicated --no-shell
ahvm get durable-dev
ahvm storage status durable-dev
ahvm stop durable-dev
ahvm storage sync durable-dev
ahvm start durable-dev
ahvm delete durable-dev

How replication works

Replicated disks commit writes to a local journal and upload them asynchronously to private S3-compatible storage, including R2. Status shows pending bytes and replication health. Missing replication state means unavailable, not synchronized. Permanent host-disk loss can lose changes that have not reached remote storage.

Sync and recovery

Explicit sync currently requires a stopped replicated VM. It succeeds only when remote durability is confirmed; it does not create a named historical checkpoint. After stop, successful synchronization and cleanup allow local cache/journal eviction while the remote disk remains. Start cold-boots that disk without restoring RAM or processes. Delete starts remote cleanup; quota and the sandbox name remain reserved until cleanup is confirmed.

Operator requirements

The standard installer does not enable the volume service. Resource-controlled hosts require a bounded volume supervisor and separate worker groups. The optional supervisor unit defaults to one CPU, 1 GiB RAM and 256 host tasks; operators configure the worker pool separately.

New VMs on the live Cloud pilot automatically use replicated storage. Existing local VMs keep local storage. See the storage guide and operator prerequisites.

The dashboard distinguishes local disks, synced replicated disks, pending writes, storage errors and unavailable status. Refreshing it does not wake machines. Missing health data is never treated as synchronized.

Disk mode is fixed at creation. Automatic wake is enabled for replicated Cloud VMs: exec, file operations and opening a new shell wake a stopped VM; status and existing-session polling leave it asleep. Cold boot does not restore old processes or sessions.

Cloud storage selection is automatic. Explicit storage overrides and the storage status/sync subcommands are currently self-hosted features; use the Cloud dashboard for replication status. After local disk eviction, live replication counters may be unavailable until the disk worker starts again.

Cloud operations

Prebooted capacity and usage visibility for AHVM Cloud administrators and users.

Prebooted Ubuntu pool

Cloud administrators can optionally keep one private prebooted Ubuntu VM per host, using 1 vCPU and 2 GiB RAM. A matching create claims it; other requests create normally. Spares count against host capacity and unused spares expire after 15 minutes. Once claimed, a VM belongs to its workspace and is never recycled into the pool. This expiry applies only to unassigned spares, not your machines. The pool starts disabled and currently requires replicated Ubuntu, the 1-vCPU/2-GiB profile and unlimited networking. Preparation and recovery run on minute controller ticks with bounded retries.

Usage and lifecycle metrics

AHVM Cloud dashboards retain usage history for 24 hours, sampled about once a minute and shown as five-minute averages. Admins see whole-host CPU and memory; users see their own VM usage and replication backlog. Missing measurements appear as gaps. Deleting a VM removes its usage history. Lifecycle timing summaries include queueing and recovery, not just boot time.

Cloud desktop

Create an Omarchy desktop and open it in the native viewer.

Use CLI and native viewer v0.3.9 or newer. Desktop access is an opt-in preview for approved workspaces and trusted workloads. GPU rendering currently shares the VM worker process; a separate renderer sandbox is not provided. Ask the operator to enable desktop access before creating a desktop.

Create and open a desktop

ahvm login
ahvm use cloud
ahvm create omarchy --image omarchy-desktop --no-shell
ahvm desktop omarchy

# Optional: use a 1920×1080 desktop (CLI v0.3.11 or newer):
ahvm desktop omarchy --resolution 1080p

# Close the viewer, then stop the VM:
ahvm stop omarchy

# Reopen it; Cloud wakes it automatically:
ahvm desktop omarchy

# Delete it when finished:
ahvm delete omarchy

Resources and lifecycle

The Cloud profile uses 2 vCPUs, 8 GiB RAM and a 40-GiB logical disk with automatic replication. It does not use the prebooted Ubuntu pool. Workspace quotas and host capacity still apply. Closing the viewer leaves the VM running; a connected viewer prevents idle stop, subject to the existing one-hour connection limit. Reopen the viewer when that limit expires.

Cold wake boots a fresh desktop from the saved disk. Files persist, but running applications, terminals and unsaved RAM state do not. Replication runs asynchronously, so permanent host-disk loss can lose writes not yet uploaded. Cold-wake latency depends on the image, host and cache state.

Display resolution

Desktop connections default to 1280×720. With CLI v0.3.11 or newer, pass --resolution 1080p for 1920×1080, or --resolution 720p to switch back. The resolution is shared by viewers connected to that VM.

Host updates and networking

For networking fixes, update the host to v0.3.10 or newer. It adds public IPv4 ping support and fixes replicated-volume recovery when many deleted VM records remain. No new guest image is needed. Test web access with curl -4 -I https://example.com, or ICMP echo with ping -4 -c 3 1.1.1.1. Older gateways can serve HTTPS while ping times out. v0.3.11 also fixes new-VM admission after repeated disk deletion and reclamation; keep existing deletion records when upgrading.

Image and applications

The current omarchy-desktop image uses Omarchy 4.0.4, with Hyprland, Quickshell, Foot, Chromium, Firefox, Nautilus, Git, Neovim, tmux, LibreOffice and Obsidian. Node.js LTS, Bun, Python, Claude Code, Codex, OpenCode and Pi are preinstalled. Sign in to coding tools with your own accounts. Other upstream AI launchers may download their tools on first use.

The desktop terminal runs as desktop, with passwordless sudo inside the VM. This is Arch Linux: install packages with sudo pacman -S PACKAGE, not apt. New Cloud desktops use the current image automatically; existing VMs keep their disk and applications. Self-hosted operators can run ahvm image pull omarchy-desktop before creating a new desktop. The complete image download is about 3.5 GiB and is cached on the host.

Images

Choose a development image and manage the host’s image cache.

Image commands

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. The current Ubuntu development image includes OpenCode 2 from the official @opencode/cli package. Cloud uses it for new ordinary VMs. Self-hosted operators can run the pull and default commands above on their server to update future VMs. Image updates affect future sandboxes; existing filesystems and snapshots remain unchanged.

Upgrades

Update the client and explicitly upgrade your servers.

v0.3.12 hardens guest device handling, VM ownership checks and snapshot cleanup. Upgrade your servers to apply these fixes; updating the client alone does not update the host runtime. No new guest image is required.

Upgrade commands

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

Networking, filesystem paths, logs, and direct server installation.

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.

Paths and service logs

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.

Server installation and removal

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.

Evaluation and origins

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.