Managing Instances

This guide covers the lifecycle and management of macpine instances, from creation to deletion.

Instance Lifecycle

A macpine instance can be in one of three states: Running, Paused, or Stopped.

Starting an Instance

If an instance is stopped, you can start it with the start command.

alpine start my-instance

Stopping an Instance

The stop command performs a graceful shutdown of the instance. The instance's disk and configuration are preserved.

alpine stop my-instance

Restarting an Instance

The restart command is a convenient shortcut for stopping and then starting an instance. This is useful for applying configuration changes.

alpine restart my-instance

Pausing and Resuming

For temporarily halting an instance without a full shutdown, you can use pause and resume. This freezes the VM's state in memory.

# Pause the instance
alpine pause my-instance

# Resume the instance
alpine resume my-instance

Viewing Instance Information

The info command provides detailed information about a specific instance.

alpine info my-instance

This will display details like its IP address, resource allocation, mounted directories, and tags.

Editing Instance Configuration

You can modify an instance's configuration after it has been created using the edit command. This opens the instance's config.yaml file in your default terminal editor ($EDITOR).

alpine edit my-instance

After saving your changes, you must restart the instance for them to take effect.

alpine restart my-instance

For a detailed breakdown of all configuration options, see the Configuration File guide.

Renaming an Instance

To change the name of an instance, use the rename command. This will also update the instance's directory in ~/.macpine.

alpine rename old-name new-name

Deleting an Instance

To permanently remove an instance, including its disk image and all associated files, use the delete command. This action is irreversible.

alpine delete my-instance

Working with Multiple Instances and Tags

Many management commands (start, stop, delete, etc.) can operate on multiple instances at once. You can also organize instances using tags.

Tagging an Instance

Use the tag command to add or remove tags.

# Add tags 'web' and 'production' to 'server-01'
alpine tag server-01 web production

# Remove the 'production' tag
alpine tag -r server-01 production

Using Tags in Commands

You can target all instances with a specific tag by prefixing the tag name with a +.

# Stop all instances tagged with 'web'
alpine stop +web

# Delete instances 'server-01' and 'server-02' in one command
alpine delete server-01 server-02