| name | minds-justfile |
| description | Use the root justfile as the canonical entry point for ANY minds task -- minds app (desktop client), pool hosts, minds environments (activate/deploy/destroy), minds deployments, and minds tests. Before running ad-hoc `uv run minds ...` / `mngr imbue_cloud ...` commands, check the justfile for a named recipe; if none exists for the task, ADD one. Use whenever the request involves the minds app, pool/leased hosts, a minds env/tier (dev/staging/production), or a minds deploy. |
Minds tasks go through the justfile
The root justfile is the canonical, auditable, named home for every
operational minds task. Recipes encode the right flags, the right env-var /
Vault wiring, and the activation guards -- so they "just work" and stay
reviewable. Hand-rolled uv run minds ... / uv run mngr imbue_cloud ...
invocations drift, leak secrets, and miss steps (e.g. deriving the pool
management key from Vault, passing the host_pool DSN for staging/production).
This is the same class of mistake as reaching for the low-level
mngr imbue_cloud admin pool create recipe in the docs instead of the
env-aware minds pool create wrapper.
The rule
When a task involves any of: the minds app / desktop client, pool hosts /
leased mode, a minds environment or tier (dev / staging / production),
a minds deployment, or minds tests --
- Look in the justfile first. Run
just --list, and/or
grep -nE 'minds|pool|deploy|env' justfile. Read the recipe's leading
comment block -- it documents prerequisites (almost all require an
activated env) and usage.
- Use the recipe. Prefer
just <recipe> ... over the underlying command.
- If no recipe fits, ADD one. Write a new, well-commented recipe that
wraps the canonical command, then use it. Keep the recipe thin -- push any
credential/secret resolution into the env-aware Python CLI rather than
reimplementing it in bash. Do not paper over a missing recipe with a one-off
shell command -- the point is a named, auditable script that the next person
(or agent) can audit and re-run. Fix stale recipes you encounter the same way.
- Keep secrets out of argv where the wrappers already handle it. The
minds env-aware CLIs read OVH creds, the pool management key, and the
staging/production host_pool DSN from Vault themselves (Vault addressing via
apps/minds/imbue/minds/envs/vault_reader.py, which defaults
VAULT_ADDR/VAULT_NAMESPACE to the HCP cluster). Don't re-export those by
hand.
Almost everything requires an activated minds env
Most minds recipes refuse to run without an activated env, by design:
eval "$(uv run minds env activate <name>)"
eval "$(uv run minds env activate --deploy <name>)"
<name> is dev-<your-user> for a personal dev env, or staging /
production. Deploy-mode (--deploy) additionally pins MODAL_PROFILE; it's
required only for minds env deploy/destroy/recover.
Current minds-relevant recipes (run just --list for the live set)
Environments / deploy:
just deploy [args] -- minds env deploy for the activated env (tier
deploys need --yes-i-mean-<tier>).
Pool hosts (leased mode):
Pool hosts are baked as bare-metal slices (lima/QEMU VMs carved on a
pre-registered + prepped bare-metal box). Baking new OVH classic VPS pool hosts
is DEPRECATED and no longer supported; existing OVH VPS rows stay listable and
destroyable. First register + prep a box with mngr imbue_cloud admin server {order,register,prep,list} (the box must be ready with a free slot).
just bake-slice-dev <region> [workspace_dir] [count] [extra flags] -- DEV
bake from a working tree; the stamped identity (repo_url + repo_branch_or_tag)
is DERIVED from the folder's origin remote + current branch (best-effort label,
uncommitted changes included). Pass --server-id <id> for the box to bake onto.just bake-slice-prod <region> <tag> [count] [extra flags] -- PRODUCTION
bake: clones the DEFAULT_WORKSPACE_TEMPLATE remote at an exact <tag> and bakes from that (content
provably equals the tag); identity = canonical remote + tag. Pass --server-id.
- Identity is never hand-typed in
--attributes (those are non-identity only,
e.g. resources). For a DEV fast-path match, the create form's repository must be
the ACTUAL git remote + the baked branch -- a local clone path resolves to the
same canonical remote, but the form value the client sends must match. Extra
flags forward to minds pool create (e.g. --mngr-source).
just list-pool-hosts -- list pool_hosts rows for the activated env.just list-servers -- list bare-metal servers with slot accounting for the
activated env (no manual DSN export needed).just prep-server <server-id> -- (re-)prep a bare-metal box for slice baking;
pool SSH key + DSN resolved from the activated tier automatically. Idempotent;
also how pre-2026-06-27 boxes get the DEFAULT_WORKSPACE_TEMPLATE image cache dir that production
--from-tag bakes require.just destroy-pool-hosts <pool-host-id> [<pool-host-id> ...] -- tear down the
named hosts in parallel: atomically claim each row (a user cannot lease it
mid-destroy), destroy its slice lima VM, and drop the row (manual teardown, e.g.
retiring old rows after baking a new pool generation; steady-state release is
automatic via the connector, and minds env destroy tears down a whole tier).
Desktop client / dev loop:
just minds-start / just minds-stop / just minds-buildjust propagate-changes <agent> -- sync local mngr into a running Docker agent.just forward-system-interface <agent> -- Cloudflare tunnel for an agent.just sync-vendor-mngr [default_workspace_template] -- sync vendor/mngr in default-workspace-template via git archive (committed snapshot; release flow). See apps/minds/docs/vendor-mngr-sync.md.just create-new-mind-repo <name> [parent_dir] -- new private DEFAULT_WORKSPACE_TEMPLATE clone.just minds-css -- compile the desktop client's Tailwind v4 stylesheet (app.css -> app.min.css).
Tests:
just minds-test-deployment [args], ...-cleanup, ...-up, ...-down,
minds-test-services-against, minds-test-deployment-only,
just minds-test-electron, just test-offload-minds-snapshot <image-id>.
Related skills
minds-dev-workflow -- the end-to-end dev iteration loop (uses these recipes).release-minds -- cut a minds release.
