Skip to main content

FAQ

Frequently asked questions grouped by topic. For step-by-step guidance, see Learning path and Quickstart.

Getting started

How do I install Midcore?
Use the install script (see Quickstart), or Homebrew / WinGet. Then run midcore --version to verify.
Do I need an account to use Midcore?
No. The CLI and VS Code extension can run with a local LLM (offline). For cloud providers, configure API keys or SSO in environment variables or .maestro/. See Environment variables.
What is the first thing I should run?
Run midcore init in your project, then midcore agent "add a README" (or any small task). See Quickstart.

Concepts

What is proof-carrying or evidence?
Midcore records the results of gates (e.g. tests, lint) in an evidence ledger. That record is the proof that a release meets your criteria—no narrative, just machine-verifiable results. See Gates & evidence.
What is the difference between Agent, Plan, Debug, and Ask?
Agent implements and edits; Plan is design only (no edits); Debug traces failures with multiple hypotheses; Ask is read-only Q&A. See How Midcore works and Best practices.
What are delivery tiers (prototype, pilot, production)?
Tiers define how many gates and how much hardening are required before a release. Prototype is relaxed; pilot is standard; production requires all gates and full hardening. See Gates & evidence.
Can I run Midcore offline?
Yes. The Desktop IDE and CLI support local (offline) LLMs. Configure your local model in settings; no internet is required. See Desktop IDE and Settings.

Reference

How do I add a custom gate?
Edit .maestro/gates.yaml: add an entry with an id, name, and command or script (e.g. run a linter or test suite). Optionally set depends_on for order. See gates.yaml and Gates reference.
Where is the full CLI reference?
See CLI reference for main commands, flags, exit codes, and examples. Use midcore --help and midcore <command> --help for the full list.
What is intent.yaml used for?
It defines your project's intent and delivery tier. The Outcome Compiler and agent use it to align scope and gates. See intent.yaml.

Web app & HTTP API

Why are there both /api/backend/… and /api/autonomy/… in the web app?
Next.js rewrites both to the same FastAPI service: /api/backend/:path* maps to /api/v1/:path*, and /api/autonomy/:path* maps to /api/v1/autonomy/:path*. Some UI code uses the shorter autonomy prefix. See Web app & API proxies and App vs autonomy API.
Where is the OpenAPI schema and Swagger UI?
On the FastAPI process: /openapi.json and /docs (default paths). The browser may not see them on the web origin unless you proxy those paths. See OpenAPI guide and API overview.
What env vars does the web container need to reach the API and auth?
Typically API_INTERNAL_URL (e.g. http://api:8000 in Compose) and, if you use the separate auth service, AUTH_INTERNAL_URL. See Environment variables and Self-hosted deployment.

Administration

How do I set up authentication for the API?
Use API keys or SSO as required by your deployment. Store credentials in environment variables or a secrets manager. See Authentication and Environment variables.
Can I self-host Midcore?
Yes. See Self-hosted deployment for deployment options and requirements.

Where to get help

Something is broken. Where do I look?
Check Troubleshooting for install, auth, gate failures, agent visibility, and CI. See Settings and Environment variables for config.
I need a definition of a term.
Use the Glossary for Outcome Compiler, gates, evidence, tiers, modes, and more.

Troubleshooting · Web & API proxies · Glossary · Learning path