last verified · 2026-07-16

Set up a machine

This page is for people who already have access to a Lumis platform. Lumis isn’t self-serve installable yet — there’s no installer that creates a platform from scratch. This is about connecting one more computer to a platform that already exists.

Binding a machine takes about ten minutes, only has to happen once per computer, and is safe to re-run any time — it’s idempotent, and it previews what it’s about to touch before it writes anything.

Before you start

You need, in order:

Access to the platform’s repository — ask whoever runs your platform to add your account — and the GitHub CLI authenticated: gh auth login.
git and python3 — most computers already have both.
At least one agent CLI, so you can run the judgment-layer commands (see The CLI). Claude Code is the most common choice; Lumis auto-detects whichever agent CLIs are on your machine and packages commands for each of them.
Optional: node and pnpm, if you also want to run the web dashboard locally.

The install

Clone the platform repository

Pick a folder that can hold sibling repositories, then clone the platform:


cd ~/code
gh repo clone <your-org>/<platform-repo>
cd <platform-repo>

Preview what the install will do


bash .lumis/scripts/install_machine.sh --check

This makes zero changes. It just prints exactly what a real run would touch, so you can see before you commit to anything.

Bind the machine


bash .lumis/scripts/install_machine.sh

It asks for confirmation before writing anything, then reports each step as it goes: adding the lumis command to your shell’s PATH, installing the matching slash-command set for whichever agent CLIs it found, granting your agent sessions read and write access to the platform’s own files, scaffolding a local .env file for secrets (never committed to git), cloning each project’s repository next to the platform repo, and setting up tab-completion for commands and project names.

It finishes with a verification pass and a warning count. Zero warnings means the machine is fully bound. Re-running the same command later — after a pull, after installing a new agent CLI — is always safe; it only changes what’s actually out of date.

After the script

Add your keys

Open the local .env file and paste in any model API keys your commands need.

Verify with the smoke test


lumis registry
lumis status

If both return real state instead of an error, the deterministic layer is wired up.

Test your agent

Open your agent CLI and run its Lumis entry point — for Claude Code, that’s /lumis:status. If it answers with real project state, the judgment layer is wired up too, and the machine is aligned.

Optional: run the dashboard


cd apps/web
pnpm install
pnpm dev

Then open the local address it prints (typically http://localhost:3002).

Staying aligned

Alignment is just git. Pull in the platform repo before you start working, and re-run the install command after a pull if commands or scripts changed — it’s idempotent, so that’s always safe.