# Asterism

Asterism boots your AI agent into a real virtual machine on hardware you own:
create, boot, ssh, snapshot, roll back. The `ast` CLI drives a local `astd`
daemon, and a macOS menu bar app ships with the first tagged release.

Site: https://asterism.run · Install: https://asterism.run/install.html
Repository: https://github.com/medicalissue/asterism · MIT OR Apache-2.0

## Install

macOS, Homebrew (builds from master, pulls in QEMU):
  brew install --HEAD medicalissue/asterism/asterism

macOS or Linux, script (prints every root command and waits for consent, so
set ASTERISM_YES=1 for unattended runs):
  curl -fsSL https://asterism.run/install.sh | sh

Linux builds from source and needs git, cargo and QEMU. Windows waits on the
QEMU + WHPX backend; nothing to install there today.

## Commands

  ast images                  list the image catalog (no daemon, no network)
  ast pull debian:13          download an image into the local store
  ast create NAME --image debian:13 --cpus 2 --mem 2G --disk 20G
  ast up NAME / ast down NAME boot it, then shut it down
  ast ssh NAME [-- CMD]       shell in the guest, or run one command
  ast snapshot NAME TAG       snapshot the disk (instance must be stopped)
  ast restore NAME TAG        roll the disk back (instance must be stopped)
  ast ls                      list instances
  ast status NAME             one instance in detail, including the ssh port
  ast logs NAME -f            follow the guest console
  ast attach NAME --volume ~/work    pass a host directory into the guest
  ast rm NAME                 delete a stopped instance and its disk

`ast --help` lists the rest, including `ast snapshots` and the device commands.
State lives in ~/.asterism (ASTERISM_HOME overrides it) and `ast` starts astd on
demand. An instance stays on the device that made it until the mesh ships.