[!IMPORTANT] This package is the agent runtime for Minion, GeekBeer's AI agent platform. It is intended to run on a Minion-managed host (provisioned via the HQ dashboard) and is not designed for standalone use.

@geekbeer/minion

AI agent runtime that runs on a Minion host (Lightsail VPS, Docker container, or self-hosted machine). It exposes a local HTTP API on port 8080, syncs heartbeats and skills with the HQ server, and runs Claude Code–based workflows and routines via tmux (Linux/macOS) or node-pty (Windows).

Supported platforms: Linux (systemd / supervisord), Windows (NSSM service + WSL), macOS (launchd).

Documentation

Full documentation lives at https://docs.minion-agent.com. Start here:

• Quickstart — provision a minion from the HQ dashboard
• Concepts — workspaces, projects, skills, workflows, routines
• Self-hosting / Provisioning — bring your own host
• Skill authoring and workflow design
• DAG workflow nodes

Japanese documentation is available at https://docs.minion-agent.com/ja/.

Install

Most users do not install this package manually — the HQ dashboard provisions hosts automatically. For self-hosted setups:

npm install -g @geekbeer/minion

Then follow the self-hosting guide to register the host with your HQ workspace.

CLI

minion-cli setup --user <USERNAME>     # Install dependencies and register services (Linux/macOS, run as root)
minion-cli configure --hq-url ... --minion-id ... --api-token ...
minion-cli start | stop | restart | status
minion-cli health | diagnose | daemons
minion-cli set-status <status> [task]
hq <subcommand>                        # HQ API helper (notes, threads, tasks, memories, etc.)

On Windows the equivalents are exposed as minion-cli-win and hq-win; on macOS as minion-cli-mac and hq-mac. See the provisioning guide for end-to-end setup.

Environment Variables

| Variable | Description | |----------|-------------| | HQ_URL | HQ server URL (leave empty for standalone mode) | | API_TOKEN | Bearer token for HQ and local API authentication | | MINION_ID | UUID assigned by HQ on provisioning | | AGENT_PORT | Local agent API port (default 8080) | | MINION_USER | System user that owns the agent process |

License

This software is licensed under the Elastic License 2.0 (SPDX: Elastic-2.0).

Copyright (c) 2026 GeekBeer Co., Ltd.