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 --versionto 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 initin your project, thenmidcore 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 setdepends_onfor 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 --helpandmidcore <command> --helpfor 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.jsonand/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:8000in 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