Installation
Already installed and looking to update instead? See Updates. A first install is covered in Getting started; this page is the reference.
Luna is one pi package. A profile chooses which of its extensions, skills and prompts
load; there are no separate packages per profile. It is delivered from its public git repository,
github.com/SATUNIX/luna (set in packages/core/distribution.json). This is a beta; see
Beta status.
Requirements
- Node.js 22.19 or newer and npm (pi's own requirement)
- git
- pi 0.85.1 or newer (
npm install -g @earendil-works/pi-coding-agent)
The one install path
npm install -g @earendil-works/pi-coding-agent
pi install git:github.com/SATUNIX/luna@v0.4.0-beta.0
pi
pi clones the release into ~/.pi/agent/git/github.com/SATUNIX/luna. On the first
interactive start Luna applies the balanced profile and asks for a /reload. Set
PI_KIT_AUTO_PROFILE=<name> to pick another profile, or 0 to leave the package unfiltered.
The repository is public, so no credentials are involved. pi runs npm install --omit=dev in
its copy of Luna, as it does for every git package; that step fetches Luna's one runtime
dependency from the npm registry (Supply chain).
The scripted installer
Use the installer when you want a specific profile chosen up front, a non-interactive install, or
project scope. It wraps pi install and pi's settings, and is idempotent:
git clone https://github.com/SATUNIX/luna.git
cd luna
node packages/core/install.ts --channel latest --profile balanced
Run it from the clone root: the installer path is relative to the current directory.
| Flag | Meaning |
|---|---|
--profile <name> |
One of the profiles in Profiles. |
--channel latest\|next\|trunk\|X.Y.Z |
Which release line to register (below). Implies git delivery. |
--git-ref <ref> |
Register an arbitrary branch, tag or commit (git delivery only). |
--mode local\|git\|npm |
local registers this checkout in place; git and npm register a released kit. |
--scope global\|project |
Global settings (default) or .pi/settings.json in the current repository. |
--only a,b / --all |
Specific extensions only, or everything. --only always adds the required base (requiredProfileExtensions in packages/core/distribution.json: tool-firewall, protected-paths, delegation-guard, effort, session-helpers) and warns about each one it adds (tests/install-marker-smoke.ts). |
--yes |
Accepted for scripts; the installer never prompts. |
--dry-run |
Print what would change; change nothing. |
--verify |
Run the repository's verify gate before registering a checkout. It runs by default only in a development checkout (npm ci done); in a plain clone it is skipped with a line saying so, because it needs the development dependencies (tests/install-marker-smoke.ts). |
--no-externals |
Skip companion packages such as pi-lens. |
--uninstall |
Remove Luna and the companions this installer registered. A companion you had already registered at Luna's pin before installing is not recorded, so uninstall leaves it (tests/install-marker-smoke.ts). |
--help / -h |
Print the usage line to stdout and exit 0 before any install work (tests/install-marker-smoke.ts). |
An unknown flag, or a value flag such as --profile with no value, stops the installer with exit
code 1 and a usage line before anything changes (tests/install-marker-smoke.ts).
A --profile name that does not match a shipped profile is an operator typo, not a crash: the
installer prints [install] Profile not found: <path>, then the real profile names, and exits 2
without a stack trace (tests/profile-transaction-smoke.ts).
The installer keeps exactly one registered copy of Luna: registering a checkout replaces a release install and the other way round, because two copies would load every extension twice.
--scope project writes only the project's .pi/settings.json and .pi/.pi-kit.json; it does not
create the global agent dir's .env (that scaffold is global-scope only). The firewall
gate files, <agent dir>/pi-kit/firewall.json and <agent dir>/pi-kit/security.json, are
machine-global, so a project-scope install (and a /profile switch in a project install) leaves
them byte-identical. When the profile asks for a different firewall mode, policy or securityLevel
than those files hold, the installer prints a WARN naming the global file and the
install.ts --scope global --profile <name> run that applies it to every session
(tests/install-marker-smoke.ts, tests/profile-transaction-smoke.ts).
Channels
| Channel | Install | Gets |
|---|---|---|
latest (default) |
node packages/core/install.ts --channel latest --profile balanced |
The newest release tag (betas count until the first stable release exists) |
next |
node packages/core/install.ts --channel next --profile balanced |
Every commit on main |
trunk (canary) |
node packages/core/install.ts --channel trunk --profile balanced |
The head of the kit's integration branch (packages/core/distribution.json git.trunkBranch, integration/luna), dogfoodable before it reaches main. Opt-in; never selected by default |
| pinned | node packages/core/install.ts --channel <version> --profile balanced |
Exactly that release (tag v<version>) |
latest needs at least one vX.Y.Z tag on the repository. Until the first release is tagged the
installer stops with a message saying there are no release tags and suggests --channel next;
it never guesses. /update channel <name> switches later. See Updates.
Profiles
Exact per-profile extension lists and counts are generated in the capability matrix (do not hand-count them; they drift). Requirements:
| Profile | Requirements |
|---|---|
balanced, lite |
Node, git, pi |
long-horizon |
Node, git, pi. Unattended runs additionally need a container engine (Autonomous runs) |
engagement |
Node, git, pi. Container deployment: packages/container/README.md |
self-improving |
Node, git, pi, Docker for memory services, optionally a second model (experimental) |
node packages/core/install.ts --channel latest --profile lite # small local models
node packages/core/install.ts --channel latest --profile balanced --scope project
Inside pi, /profile switches profile in place and verifies the result. See Profiles.
Install modes
| Mode | Command | When |
|---|---|---|
| Release from pi | pi install git:github.com/SATUNIX/luna@vX.Y.Z |
Normal use; the profile is applied on first start |
| Release from the installer | node packages/core/install.ts --channel <latest\|next\|trunk\|X.Y.Z> --profile <name> |
You want the profile chosen up front or a scripted install |
| Local checkout (editable) | node packages/core/install.ts --profile <name> --yes |
Developing Luna: pi loads the checkout in place, edit and /reload |
| Project auto-install | Ship .pi/settings.json in a repository |
pi auto-installs on first trusted start |
| npm (not published yet) | npx @satunix/pi-system --profile <name> |
Only once npm delivery is switched on (Releasing) |
From a checkout
git clone https://github.com/SATUNIX/luna.git && cd luna
npm ci --ignore-scripts
node packages/core/install.ts --profile balanced --yes
# Specific extensions only (the required base is added to them)
node packages/core/install.ts --only memory-local,verify-gate --yes
Coming from the private GitLab source
Installs made from the earlier private GitLab source move by installing the public Luna package and running its installer, which keeps your profile and hand edits and never contacts the old host; see Migration.
After install
- Run
pi. /reloadapplies extension changes without restarting.pi listshows the registered packages;/menuand/footer statusshow what is active.
Web console
The optional web console is covered in Web console: it is token-authenticated and bound to loopback by default.
Uninstall
# Removes Luna and the companions the installer registered (from the clone root):
node packages/core/install.ts --uninstall
The command auto-detects the install state marker: a project marker at
<current dir>/.pi/.pi-kit.json wins if it exists, otherwise the global marker at
~/.pi/agent/.pi-kit.json is used. Pass --scope project or --scope global to force one. After
a project-scope install, run it from the repository root so the project marker is found and
pi remove ... -l runs with the matching scope. A project uninstall deletes only the project
marker; the global marker is left untouched.
The same precedence is used by the runtime readers that resolve install state (/update,
/profile, /console).
Memory backends (self-improving profile — experimental)
packages/container/mcp-servers/memory-mcp/docker-compose.yml starts a Qdrant vector store
(qdrant/qdrant v1.20.0, the unprivileged image, pinned by digest) with its data in the
qdrant-data volume. The store holds memories a mem0 server later puts into prompts, so the compose
file never publishes it unauthenticated:
- the port binds
127.0.0.1only (6333, orQDRANT_PORT); nothing on the network can reach it; QDRANT_API_KEYis required:docker composerefuses to start without it, and Qdrant answers401to any request that does not send the key in anapi-keyheader. Give your mem0 server the same key;- the container runs as a non-root user (uid 1000) with every capability dropped and
no-new-privileges.
tests/compose-policy-smoke.ts checks the loopback bind, the required key and the hardening options
in this file. It does not run Qdrant; the 401 was checked by hand against the pinned image.
export QDRANT_API_KEY="$(openssl rand -hex 32)"
docker compose -f packages/container/mcp-servers/memory-mcp/docker-compose.yml up -d
To reach the store from another machine, put an authenticated, TLS-terminating proxy in front of it rather than widening the bind.
A volume first created by the root-run image is owned by root, which the unprivileged image
cannot write. Give it to uid 1000 once before starting:
docker run --rm -v pi-kit-memory-mcp_qdrant-data:/data alpine chown -R 1000:1000 /data.
No kit code talks to it. The memory MCP server keeps its records in SQLite and JSONL files under
PI_KIT_MEMORY_MCP_DATA_ROOT and does not use Qdrant; the store is there for a mem0 server you run
yourself, which can use Qdrant as its vector store.
Upgrading a qdrant-data volume from an older Qdrant. Qdrant supports upgrading only from one
minor release to the next, migrates the storage on first start, and cannot be downgraded. A volume
written by v1.12.6, the previous pin, does not start under v1.20.0: the server stops with
Failed to deserialize ... segment.json: unknown variant 'on_disk'. Either step through the latest
patch of each minor release, starting each one on the volume until it reports ready, then stopping
it (v1.13.6, v1.14.1, v1.15.5, v1.16.3, v1.17.1, v1.18.3, v1.19.2, then v1.20.0; from v1.16.1 the
start also moves RocksDB storage to Gridstore, which v1.18 and later require), or remove the volume
(docker compose ... down -v), which discards whatever a mem0 server stored in it. Back the volume
up before stepping. Nothing in Luna's tests runs Qdrant.
memory-mem0 (an experimental extension in the self-improving profile) additionally
needs an external mem0 REST server, which this repo does not ship. Point it at your own mem0
instance:
# Set env var (add to ~/.pi/agent/.env) — only if you run your own mem0 server
MEM0_API_URL=http://localhost:8000
Environment variables
| Var | Extension | Default | Purpose |
|---|---|---|---|
PI_KIT_GUIDELINES_PATH |
guidelines | GUIDELINES.md |
Path to guidelines file |
PI_KIT_TODO_FILE |
todo | TODO.md |
Path to todo file |
PI_KIT_PROTECTED_PATHS |
protected-paths | — | Semicolon-separated protected paths (denylist) |
PI_KIT_WRITE_ALLOWLIST |
protected-paths | — | Semicolon-separated allowlist; blocks writes outside it (dream/print mode) |
PI_KIT_FIREWALL_POLICY |
tool-firewall | shipped default-deny policy | Path to a custom firewall policy JSON |
PI_KIT_FIREWALL_APPROVALS |
tool-firewall | <agent dir>/pi-kit/firewall-approvals.json |
Where remembered approvals are stored (Security) |
PI_KIT_FIREWALL_PROMPT_TIMEOUT_MS |
tool-firewall | 900000 |
How long an approval card waits before the call is refused as uncertain |
PI_KIT_EFFORT_CONFIG |
effort | <agent dir>/pi-kit/effort.json |
Saved effort default and limit overrides (Effort) |
PI_KIT_AUTO_PROFILE |
session-helpers | balanced |
Profile applied on the first interactive start; 0 disables |
PI_KIT_LEAN_CTX |
session-helpers | — | Set to 0 to disable the lean-ctx preflight warning |
PI_KIT_UPDATE_CHECK |
kit-update | on | 0 turns the background update check off (Updates) |
PI_KIT_MEMORY_DIR |
memory-local | ~/.pi/agent/memory-local |
Memory store directory |
PI_KIT_COMPACT_THRESHOLD_TOKENS |
trigger-compact | 100000 |
Token count that triggers auto-compaction; locks out /compact-threshold when set. Without it, /compact-threshold <amount> (e.g. 500k) persists to ~/.pi/agent/pi-kit/trigger-compact.json |
PI_KIT_VERIFY_ON_TURN |
verify-gate | 0 |
Set to 1 to run the check command after successful write/edit tools when the assistant finishes its tool sequence; projects without a verify script are skipped |
PI_KIT_VERIFY_CMD |
verify-gate | unset | Check command for /verify; overrides scripts.verify |
PI_KIT_VERIFY_REVIEW |
verify-gate | on | 0 turns off the independent completion reviewer in /verify and verify_completion |
PI_KIT_VERIFY_REVIEW_MODEL |
verify-gate | current model | Reviewer model as provider/id |
PI_KIT_VERIFY_REVIEW_TIMEOUT_MS |
verify-gate | 900000 |
Reviewer timeout |
PI_KIT_VERIFY_PENDING_TTL_MS |
verify-gate | 1800000 |
How long a "verification pending" marker stays valid, in ms; an older marker is treated as absent |
MEM0_API_URL |
memory-mem0 | — | mem0 REST service URL |
MEM0_API_KEY |
memory-mem0 | — | mem0 API key (if auth enabled) |
MEM0_USER_ID |
memory-mem0 | pi-agent |
mem0 user/agent ID |
DUAL_REVIEW_MODEL |
dual-review | — | Second model name for reviewer agent |
PI_KIT_TASK_GRAPH_LEASE_MS |
task-graph | 3600000 |
How long a task_next claim lasts without a task_update; an older claim returns to pending. 0 disables expiry |
PI_KIT_COST_INPUT_PER_MTOK |
custom-footer | — | Override input-token dollars per million tokens |
PI_KIT_COST_OUTPUT_PER_MTOK |
custom-footer | — | Override output-token dollars per million tokens |
PI_KIT_COST_CACHE_READ_PER_MTOK |
custom-footer | — | Optional cache-read dollars per million tokens |
PI_KIT_COST_CACHE_WRITE_PER_MTOK |
custom-footer | — | Optional cache-write dollars per million tokens |
PI_KIT_TIPS |
custom-footer | on | 0 hides usage tips on the working line |
PI_KIT_TODO_WIDGET |
custom-footer | on | 0 hides the todo checklist widget |
See status-bar-and-costs.md for .pi-kit/costs.json, fallback user config, and /footer commands.