FAQ

Short answers to the questions that come up most. Each links to the page that goes deeper.

What exactly is mini-ork?

A task operating system for agents: it takes a goal, classifies it into a task class, plans a DAG of agent nodes, dispatches each node to a model lane, runs gates against the result, and records a verdict. The verdict is derived from what executed, not from a model's opinion of its own output. See Overview and Core concepts.

How is it different from LangGraph, CrewAI or AutoGen?

Those are orchestration libraries: you describe a graph and they run it. mini-ork adds the layers that decide whether the work is shippable — a verification stack with an execution-anchored oracle, cost governance across heterogeneous providers, and a learning loop that feeds only verified outcomes back. You can use it as a library through the Python SDK.

Do I need an API key to try it?

Yes, for any real run — one or more provider credentials configured in agents.yaml and the vault. mini-ork doctor tells you which lanes are ready. Cheaper open-weight lanes are enough to start. See Providers and lanes.

Which models and providers are supported?

Provider kinds cover OpenAI-compatible endpoints, Anthropic, MiniMax, Kimi, GLM and a native Codex transport. You bring the endpoint and the key; routing is by role, and chains fall back across lanes. See Providers and lanes.

What does "PROVEN" actually mean?

That every required gate ran and passed for this change in this run. It is evidence, not a proof of universal correctness. If no gate produced a trustworthy signal, the verdict is UNVERIFIED; if the checks had no discriminating power, the run is VACUOUS — never green by default. See Verification and gates and Results.

How much does a run cost?

The certificate demo costs about $0.03 and takes 1.5–2 minutes on a small lane. Full held-out tasks averaged $0.42 per task with open-weight lanes. Cost is metered per model at list price, with a daily circuit breaker and a cost-pause sentinel you can raise or wait out. See Cost control.

Does it work without Docker or a server?

Yes. The simple tier needs only Python 3.11+ and the repository: no daemon, no cloud account, no network round-trip beyond your model provider. The secure, cloud-scalable tier is optional and selected by the same configuration files. See Installation and Sandboxing.

What are the platform requirements?

Python 3.11 or newer, a POSIX shell for the installer, and git. Linux and macOS are the tested platforms. The installer can also install system dependencies behind INSTALL_SYSTEM_DEPS. See Installation.

Is it open source?

Apache-2.0. The source, schemas, recipes and operator docs are in the repository.

Can mini-ork modify its own prompts and workflows?

It contains a self-improvement loop that can propose, score and promote such changes — with a per-task no-regression gate. It ships off by default. If you enable it, read the warning in the README first. See Self-improvement.

Where does state live?

Per project: .mini-ork/state.db (SQLite) plus .mini-ork/runs/<run-id>/ for per-run files and .mini-ork/certificates/ for certificates. MINI_ORK_HOME overrides the home; MINI_ORK_DB overrides the database. See Environment and Inspecting state.

A run failed. Do I start over?

No — resume it. mini-ork run --resume <run-id> skips succeeded nodes, re-dispatches the rest, and prints the skip/dispatch sets before executing. Resuming an unknown id is a hard error, never a silent fresh start. Rewind with --checkpoint-id. See Recovery.

My tests are already red. Can it still prove a fix?

Not reliably. A run cannot prove a change against a broken baseline — the test gate fails on the base as well as the head. Fix the baseline first, or scope the verifier to the affected tests via the artifact contract. See Failure triage.

Can I add my own task type or recipe?

Yes. Add a directory under recipes/ with task_class.yaml, workflow.yaml and artifact_contract.yaml; mini-ork validate checks it and mini-ork recipe-eval lints it before a run. See Recipes and Schemas.

Can I use it in CI?

Yes. mini-ork certify is the CI-shaped command: point it at a base and head commit and gate on the verdict and exit code. It writes a certificate with a reproducible digest, which is the artifact to archive. See certify and Certifying a change.

Does it send my code anywhere?

Only to the model providers you configure, using the credentials you supply. There is no telemetry service. The local simple tier keeps all state on disk. See Security.

How should I write a kickoff?

State one outcome, the files or area in scope, and a checkable acceptance condition. A tight kickoff produces a tight plan; an oversized one produces planner schema failures. See Writing a kickoff.

Is there a web UI?

Yes — a local FastAPI app with a live event stream, run detail, a DAG overlay and failure triage. Reads are open locally; writes require a token. See Web app.

Can several agents work at once without colliding?

Yes. Worktrees isolate checkouts, and --owns claims a file surface so two concurrent agents cannot both edit the same files. See Worktrees and concord.

What is the difference between run, execute and certify?

run is the full lifecycle for a kickoff. execute runs a single prepared stage or workflow. certify answers one question — does this change hold? — and emits a certificate. See run, Lifecycle commands and certify.

How do I upgrade or uninstall?

mini-ork update applies state migrations and reports drift; mini-ork doctor checks the result. Uninstall is removing the install directory and, per project, .mini-ork/. See Installation.

What does it not do?

It does not certify subjective or untestable work, does not guarantee cheaper routing at equal correctness (not yet shown), and does not run unattended self-improvement unless you turn it on. The limits are stated on the landing page and in Results.

Where do I report a bug or ask a question?

Open an issue on GitHub. For security reports, follow SECURITY.md rather than filing publicly.