magehand
The developer CLI for building apps on davidlarrimore's homelab, the same way on the owner's MacBook (Claude Code) and in OpenClaw's VM (its coding workers). It reads platform state and runs apps locally. It never deploys: changes go through pull requests.
It is public because it holds nothing sensitive. Every command needs access
that only the owner has: the private homelab repos on GitHub, the private
*.lab network, and an authentik passkey for
OpenBao.
Install
brew install uv # once
uv tool install magehand
magehand setup # once per machine
magehand setup checks GitHub (gh auth login first) and which container
runtime this machine has (only needed for database blocks; see magehand runtime below), makes sure the homelab's *.lab
names resolve (if they don't, it asks for the homelab's DNS address, your home
gateway, and points only *.lab lookups at it; magehand setup --undo
reverses that), then signs you in and installs the homelab-app skill for Claude Code (and Codex). Every other command assumes this is done.
Upgrade with magehand upgrade (any command says, at most once a day, when a new version is out).
Commands
| Command | What it does |
|---|---|
magehand guide [topic ["section"]] |
The app platform guide, live from homelab-apps docs/platform/; magehand guide catalog for blocks and models |
magehand guide search WORDS |
The guide sections (homelab-apps docs/platform/ and AGENTS.md) that best match a question, e.g. magehand guide search web search |
magehand app [name] |
The app's blocks, every env var its pod gets and where it comes from, its URLs. In an app repo the name is the repo's |
magehand check [name] [--code DIR] [--apps-dir DIR] [--manifests-only] |
The platform's rules for the app's code and its homelab-apps deployment: block keys and options, optional: true keys, Secrets that aren't blocks, the image, env the code reads but the pod doesn't set, direct AI/search provider calls, own login, database files. Each finding names the guide section; exit 1 on errors. Run before every push; CI (homelab-apps build-app.yaml) runs it too, with --apps-dir |
magehand login |
Sign in to OpenBao through authentik (passkey) with role dev: read-only access to agent apps' LiteLLM keys, 1h (8h max). The token is kept in the macOS Keychain |
magehand dev up|down|status |
Containers (with the chosen runtime) for the app's postgres/redis blocks (the blocks' own pinned images) on a per-app network, and local values for secret blocks |
magehand run [--no-proxy] -- CMD |
Runs CMD with the env the app's pod gets: values from its Deployment, the LLM key from OpenBao, databases from dev up. Precedence: manifest < the repo's .magehand.env (committed, non-secret overrides such as WEB_DIR=./web) < your shell < secrets. A proxy on 127.0.0.1:8080 adds the X-authentik-* headers Traefik would, as you |
magehand run --container [--no-build] [-- CMD] |
Builds the repo's Dockerfile and runs the image as its pod runs: read-only, /tmp tmpfs, the pod's user, no capabilities, exactly the pod's env. Secrets go in as -e NAME only, never in the image, argv or on disk |
magehand setup [--undo] [--dns ADDRESS] |
Once per machine: GitHub, the container runtime, *.lab name resolution (the only step that may ask for your password), sign-in |
magehand skill [--install] |
The homelab-app skill: tells Claude Code and Codex to use app, guide search and check while working on app code. setup installs it ($CLAUDE_CONFIG_DIR or ~/.claude, and $CODEX_HOME or ~/.codex if Codex is installed) |
magehand runtime [use docker|podman|none | auto] |
The container runtime for local postgres/redis blocks and run --container. Detected without sudo (<cli> info): the docker CLI of Docker Desktop, OrbStack, Colima or Rancher Desktop (dockerd), or Podman; Rancher Desktop in containerd mode is explained, not supported. Automatic picks the first running one; use pins one (or none: no containers; magehand run -- CMD still works for apps whose blocks are llm and secret only); MAGEHAND_RUNTIME overrides. Saved in ~/.config/magehand/config.json |
magehand doctor |
Checks GitHub access, that openbao.lab is reachable, the sign-in, and shows the container runtime (missing is fine unless the app has database blocks) |
magehand upgrade |
Upgrades magehand the way it was installed (uv tool upgrade, pipx upgrade or pip in its venv) and refreshes the homelab-app skill if you installed it. Never automatic: a release runs on your Mac, so you run it. Every other command prints a one-line notice (stderr, at most once a day, never in CI or scripts) when a newer version is tagged on GitHub; MAGEHAND_NO_UPDATE_CHECK=1 turns it off. OpenClaw's VM refuses it: its version is pinned in homelab platform/openclaw/vm/versions.env |
magehand version |
The installed version, and whether a newer one exists |
Development
uv venv && uv pip install -e .
.venv/bin/python -m unittest discover -s tests
Python 3.9+ (the Mac's system Python works). Stdlib plus PyYAML. Releases:
bump version in pyproject.toml, merge, then tag vX.Y.Z. The release
workflow builds and publishes to PyPI through trusted publishing (no stored
token). OpenClaw's VM installs a pinned version from homelab
platform/openclaw/vm/versions.env.
Never commit secrets, tokens, IP addresses or email addresses: this repo is public.
1 maintainer
Metadata
1 maintainer
Release files for magehand 0.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| magehand-0.4.0.tar.gz | 30.9 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| magehand-0.4.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 57.1 kB
Release files / magehand-0.4.0.tar.gz
| Download URL | magehand-0.4.0.tar.gz |
|---|---|
| Size | 30.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
248c311debacdea0c1b1b43e8148ed04b3a9698bcabb268accc3a79d304a09bf
|
|
BLAKE2b-256 checksum How to use checksums |
5d01e62ab1259ec51e5aafc96fd11d3f6c653d65beb3e3fdf1488f1c49bffac5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 2, 2026.
Transparency logRelease files / magehand-0.4.0-py3-none-any.whl
| Download URL | magehand-0.4.0-py3-none-any.whl |
|---|---|
| Size | 26.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
aedd7896e73c1c6b2b647618132d33a3d2d7184960a2a9751781b09c67d88826
|
|
BLAKE2b-256 checksum How to use checksums |
979dfdd4efa614b18d87ebcfdf2214ee661ee9085381c4311ada6f5def266db6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 2, 2026.
Transparency log
