@developers-homelab/runestone-cli
v2.1.0
Published
Cross-platform CLI tool for the runestone Docker development environment
Maintainers
Readme
Runestone
![]()
This project was forked from druidfi/stonehenge 5.2. The main change is replacing Makefile-based installation and management with an npm global tool that is easier to use across platforms. If you like this project, please also support the original idea by starring druidfi/stonehenge 5.2.
Introduction
- Local frontend and backend projects can be tested with
SSL certificatesand alocal domain, avoiding many localhost-related issues. - Ports 80 and 443 can be reused, reducing port conflicts between multiple local projects.
- You do not need to edit the hosts file just to use a
local domain.
Core Components
- traefik: Reverse proxy that routes requests to the matching project.
- mailpit: SMTP testing tool that captures and displays sent emails.
- npm tool: Command line tool for managing and running Runestone.
- @mkcert/node: Generates locally trusted SSL certificates.
Requirements
- Latest Ubuntu LTS, or Windows 10/11 with WSL2 installed.
- Docker 29.0+ with Docker Compose V2.
- Node.js 22.0+.
Installation And Usage
Install
npm install -g @developers-homelab/runestone-cliThis installs the 2.x line. 1.2.x still receives bug fixes — see Versions And Support.
Check Host Environment
Runestone needs Docker, Docker Compose, and platform certificate tools to be available on the host machine.
You can check the environment before setup, or let runestone doctor help with supported fixes when setup reports missing tools.
runestone doctorStart
The first time you run it, an interactive setup wizard will appear. To change settings later, run runestone setup.
runestone upStop Or Shut Down
Note: If Runestone was not stopped before shutting down your system, it will start automatically on the next boot.
Stop:
runestone stopShut down (stop and remove containers):
runestone downDNS For Containers (Optional)
A Runestone domain resolves to 127.0.0.1, which inside a container is the container itself — so containers cannot reach each other by domain. The optional DNS feature fixes that by giving containers a resolver that knows your Runestone domains.
It is off by default, and turning it on is invasive: it adds an entry to the Docker daemon's own configuration and requires a Docker restart, which stops every container on the machine. After that, DNS for every container on the machine goes through a Runestone container.
Read the full explanation before enabling it — what it changes, how to turn it off, and how to remove the entry by hand: DNS documentation (繁體中文 | 日本語).
How the domains themselves resolve — the Runestone domain, traefik.me's address-decoding, and why the feature is IPv4 only — is in DOMAINS.md (繁體中文).
runestone dns enable --dry-runThat prints exactly what would change, with your real values, and writes nothing.
Certificate Management
List Certificates
Shows the certificate list from the .runestone/certs directory.
runestone certs listAdd Certificate
Adds a certificate generated by @mkcert/node to the .runestone/certs directory and creates the dynamic Traefik configuration.
runestone certs create <domain>Remove Certificate
Removes the certificate from the .runestone/certs directory and deletes the matching dynamic configuration.
runestone certs remove <domain>Service Management
Add Service
Adds a routed service and creates the matching dynamic Traefik configuration. When required arguments are missing or invalid, Runestone enters interactive mode to complete them.
runestone service add <service name> --route <domain> --url <url with port> --group <group name>List Services
Shows configured routed services.
runestone service listRemove Service
Removes a routed service and deletes its matching dynamic Traefik configuration.
runestone service remove <service name>Project Integration
Runestone can tell an AI coding agent how to connect your project to it, so you do not have to explain it yourself.
Install the guidance where your agent tools already look:
runestone skill installIt detects which tools the project uses and writes only for those. Use --dry-run first to see every path it would touch. runestone skill status shows what is installed, and runestone skill remove takes it back out.
Or print the guidance and paste it yourself:
runestone docs --ai-contextAdd a topic — service, state, troubleshoot or overview — for the rest. Every topic ends with the list of the others, so an agent that runs the bare command finds them on its own.
Or connect Runestone as a read-only MCP server:
runestone mcp config --client claudeThe full explanation, including what an agent will not do on your behalf, is in AI agent documentation (繁體中文 | 日本語).
Versions And Support
| Line | Status | Support | | --- | --- | --- | | 2.x | Current | Where new features happen | | 1.2.x | Final feature release of 1.x | Bug fixes only, until 2026-11-30 |
2.x is the current line, and npm install -g @developers-homelab/runestone-cli installs it.
1.2.0 was the last feature release of the 1.x line. It receives bug fixes only: no new commands, no new options, no behavior changes. Support for 1.2.x ends on 2026-11-30.
Upgrading from 1.x rewrites your compose.yml on the first up, keeping the old file as a .bak beside it. To stay on the 1.x line while it is still supported:
npm install -g @developers-homelab/runestone-cli@1More Help
runestone --helpTodo
- [ ] Test on macOS (M1/M2/M3/M4/M5).
