Installation¶

mini-ork is a Python runtime plus a CLI entrypoint. It needs Python 3.11 or newer, git, and sqlite3. There is no server to run and no database to provision: each project gets a local .mini-ork/ home.

Requirements¶

Requirement	Why
Python 3.11+	The runtime uses `match`, `tomllib`, and modern typing
`git`	Worktrees, diffs and certificate bases
`sqlite3`	Run state and the learning ledger
A provider credential	At least one lane in `providers.yaml` must resolve

Optional: claude or codex CLIs if you route lanes through them, and Docker or a cloud sandbox provider if you want isolated node execution.

One-line installer¶

curl -fsSL https://raw.githubusercontent.com/SourceShift/mini-ork/main/install.sh | sh

The script checks for a suitable Python, clones the repository, initialises the ui/ submodule on a best-effort basis, installs system dependencies when it can, and then hands off to scripts/full_install.py.

Installer knobs¶

Variable	Default	Effect
`MINI_ORK_INSTALL_DIR`	`$HOME/.local/share/mini-ork`	Where the engine checkout lives
`MINI_ORK_REPO_URL`	`https://github.com/SourceShift/mini-ork.git`	Source repository
`MINI_ORK_REF`	`main`	Branch or tag to install
`INSTALL_SYSTEM_DEPS`	`1`	Set `0` to skip OS package installation
`PYTHON`	first of `python3.12`, `python3.11`, `python3`	Interpreter to use

Example — pin a release and skip system packages:

INSTALL_SYSTEM_DEPS=0 MINI_ORK_REF=v0.9.0 \
  curl -fsSL https://raw.githubusercontent.com/SourceShift/mini-ork/main/install.sh | sh

Re-running the installer over an existing checkout fast-forwards it. If the checkout has local changes the fetch is reported and left alone, so an in-place upgrade never discards work.

From source¶

git clone --recurse-submodules https://github.com/SourceShift/mini-ork.git
cd mini-ork
make install

make install installs the runtime dependencies and exposes bin/mini-ork. To use the CLI without installing it globally, call ./bin/mini-ork directly.

The ui/ submodule

ui/ holds the IDE crate. Nothing in the Python runtime reads it, so a clone without the submodule still runs every command — it only leaves the desktop IDE surface unavailable.

Initialise a project¶

Installation puts the engine on your machine; a project still needs its home:

cd /path/to/project
mini-ork init

This creates .mini-ork/ with config/, runs/, state.db, INBOX/ and locks/, seeds the shipped task classes, and appends the ignore rules. It is idempotent: existing files are reported as already present and are not overwritten.

Commit .mini-ork/engine so every collaborator resolves the same engine version. Everything else in .mini-ork/ is generated state.

Where things live¶

Path	Meaning
`$MINI_ORK_HOME`	Project home. Defaults to `<cwd>/.mini-ork`
`$MINI_ORK_DB`	State database. Defaults to `$MINI_ORK_HOME/state.db`
`$MINI_ORK_PROVIDERS`	Overrides `$MINI_ORK_HOME/config/providers.yaml`
`$MINI_ORK_AGENTS`	Personal lane overlay (default `config/agents.local.yaml`)
`$MINI_ORK_ROOT`	Engine checkout root

The full list is in Environment variables.

Verify the install¶

mini-ork doctor

A healthy install reports:

sqlite3, git, curl and python3 present;
the engine root and version;
whether the home database was migrated by this engine;
which provider families have credentials;
the vault backend chain and whether it has a protection gap.

Then run the static checks against a project:

mini-ork validate
mini-ork garden

validate checks recipes, providers and environment before a run. garden detects drift: colliding task classes, orphaned runs, stale locks.

Upgrading¶

mini-ork update

update applies pending schema migrations and reports configuration drift between your home and the current engine defaults. It does not overwrite your configuration.

If the installer and the project engine disagree, doctor says so explicitly: home DB last migrated by vX, this engine is vY. Use mini-ork migrate from the engine you intend to keep.

Uninstalling¶

Remove the project state:

rm -rf .mini-ork

Remove the engine:

rm -rf "${MINI_ORK_INSTALL_DIR:-$HOME/.local/share/mini-ork}"

Delete the mini-ork shim from your PATH if full_install.py created one.