Provisioning and Management

This page covers the minion lifecycle from creation to shutdown and recovery.

Provisioning flow

1. Select “New Minion” from the HQ dashboard
2. A cloud server is created for the minion
3. The minion server starts automatically
4. A secure tunnel is created, making the minion accessible via a unique URL
5. A heartbeat is sent to HQ, and the status changes to online

Minion statuses

Status	Description
provisioning	Server is being created
online	Running normally
offline	Heartbeat lost
stopped	Manually stopped
expired	Trial period ended (state saved)

Lifecycle operations

Stop

Stop a minion from the HQ dashboard or API. A snapshot is created on stop to preserve state.

Resume

A new instance is created from the snapshot, restoring the state from before the stop.

Delete

The snapshot and instance are permanently deleted. This operation cannot be undone.

Self-hosted minions

You can run a minion on your own hardware (Windows PC, Mac mini, etc.) instead of a cloud VPS.

1. Create a self-hosted minion from the HQ dashboard
2. Install @geekbeer/minion on the target machine
3. Run the setup command with the provided credentials

Headless operation (no display)

Cloud VPS minions use a virtual display (Xvfb), so VNC works without a physical monitor. Self-hosted machines (Windows / macOS) mirror the physical display, so VNC will show a black screen if no display is connected.

If you plan to run your machine without a monitor, plug an HDMI dummy adapter into the HDMI port. The OS will detect it as a connected display, and VNC will work normally. No software changes are required.

Monitoring

The HQ dashboard provides visibility into:

• Heartbeat — Minion liveness status (30-second intervals)
• Uptime — Cumulative uptime and usage tracking
• Execution logs — Workflow/routine execution history