Quick Start Guide

This guide will walk you through the basic workflow of creating, interacting with, and managing a macpine virtual machine.

1. Launch Your First Instance

The alpine launch command creates and starts a new VM. By default, it uses sensible settings (2 CPUs, 2048MB RAM, 5GB disk) and matches your host's architecture.

# Launch an instance with default parameters
# The command will output a randomly generated name, e.g., 'launched: nifty-result'
alpine launch

You can customize the resources for your VM using flags:

# Create an x86_64 instance with 4 CPUs, 4GB RAM, and a 20GB disk
alpine launch -a x86_64 -c 4 -m 4096 -d 20G

2. List Your Instances

The alpine list command shows all your instances and their current status.

alpine list

Output will look similar to this:

NAME             STATUS      SSH    PORTS   ARCH      PID     TAGS
cheerful-result  Running     2022           aarch64   26568
nifty-result     Running     3022           x86_64    57206

3. Connect to Your Instance

By default, macpine forwards an SSH port from the host to the VM. You can connect using the alpine ssh command. The default password for the root user is root.

# Replace 'cheerful-result' with your instance's name
alpine ssh cheerful-result

This will drop you into a shell inside the Alpine Linux VM.

4. Execute a Command

To run a single command without opening an interactive shell, use alpine exec:

alpine exec cheerful-result -- "uname -a"

# Expected output:
# Linux cheerful-result 5.15.60-0-virt #1-Alpine SMP Mon, 15 Aug 2022 13:33:57 +0000 aarch64 Linux

5. Share and Backup Instances

macpine allows you to package an instance into a distributable archive file.

  1. Publish the instance: This creates a .tar.gz archive in your current directory. 

    alpine publish cheerful-result

  2. Delete the original instance (for demonstration purposes): 

    alpine delete cheerful-result

  3. Import the instance from the archive: This restores the VM. The new instance will have the same name as the archive file (without the extension). 

    alpine import cheerful-result.tar.gz

6. Stop and Delete

When you're finished with an instance, you can stop it or permanently delete it.

# Stop the instance (can be started again with `alpine start`)
alpine stop cheerful-result

# Delete the instance permanently (this action is irreversible)
alpine delete cheerful-result