Modern development has two audiences: the people on your team, and the AI agents working alongside them. Both suffer from the same disease — every project is shaped differently. Every repo has its own layout, its own env-var loading order, its own half-documented way to start the stack. Humans burn onboarding time relearning it; agents burn tokens re-exploring it, on every single session.
MechCrate's bet is that consistency is the highest-leverage investment you can make in the agent era. When every project in every organization you touch has the same folder contract, the same make dev, the same compose conventions, and the same URLs, then:
- A developer who knows one mx project knows all of them.
- An agent lands in familiar terrain every time — less exploration before the first useful edit, and one MCP server that understands any mx project instead of per-repo bespoke discovery.
- Your organization's accumulated wisdom travels with the framework: an MCP server and a techniques corpus (RAG over curated engineering docs, stored in a Postgres you control) mean agents can look up how your stacks are built instead of guessing — with no SaaS middleman between the agent and your stack.
The Docker/ecosystem machinery below is the foundation that makes that possible. It was built the way real developers actually work — and that story is worth telling in full.
The problems it exists to solve
You can't run all twelve services locally
Real ecosystems have 10+ services. Running all of them on a laptop — or in a shared dev environment — is not feasible, and most of them are irrelevant to the feature you're building today.
mx makes the subset the unit of work. Every service gets its own atomic compose file (docker/compose/<service>.yml + <service>.dev.yml override) — nothing forces all-or-nothing:
make dev # the whole stack
make dev s=api # just the service you're working on
make dev s="api worker" # or the handful the feature actually touches
The quotes in s="api worker" are required, because make splits on whitespace and an unquoted second name reads as another goal. dev, up, down, stop, restart and logs all take a list, since the compose verb underneath accepts several service operands. build, run, exec and sh act on exactly one image or container, and refuse a list out loud rather than silently using the first name.
Baseline files describe production shape; dev overrides add hot-reload mounts, debug ports, and relaxed health checks. Nothing about "what runs where" lives in tribal knowledge.
Switching organizations shouldn't mean tearing down your stack
If you work across multiple organizations — or just multiple products — the usual routine is misery: spin down ecosystem A's containers so ecosystem B's ports don't collide, lose your state, repeat tomorrow.
The mx router is a single global Traefik instance that every mx project registers with. Application services publish no HTTP host ports — Traefik routes to them by hostname, so two ecosystems' web apps never collide. (Dev overrides do expose backing services like Postgres and Redis to the host for local GUI tools, on a port Docker allocates rather than a pinned one, so a second stack never finds the number taken.) Each service is reachable at a stable hostname:
http://api.localhost http://admin.localhost http://docs.localhost
Multiple ecosystems coexist on one machine. Switching contexts is cd — not teardown. One router, installed once (mx router install && mx router up), serves everything. Container names no longer stand in the way either: with container_name gone from every shipped compose file, two projects that both declare a db service coexist.
Two copies of the same shape coexist as well, with no hand edits. Dev overrides no longer pin host ports: the ports tooling dials on demand (Postgres, Redis, the Node inspector, worker metrics, Vite, Inertia SSR) publish on 0, so Docker picks a free one per stack and docker compose -p <project> port db 5432 prints it. Traefik router, service and middleware names carry the compose project, so two stacks that each scaffold an api service write two entries into the router table instead of fighting over one.
The one residual, stated plainly: both stacks run, but a hostname belongs to one of them. Default domains are untouched, so the second stack claims its own by exporting a knob rather than editing a shipped file: API_ROUTER_HOST=api-two.localhost make dev. Until it does, the second stack is up and healthy but not reachable at api.localhost.
Scaffolding should carry wisdom, not boilerplate
Starting a new service usually means cobbling: copy a Dockerfile from the last project, hand-port the test harness, rediscover the admin-panel setup, re-solve deployment. Piecemeal, every time.
mx recipes are production-shaped service definitions that carry the accumulated decisions of the stacks they came from — dependency choices, testing setup, admin tooling, dev overrides, deploy configuration — applied in one motion:
mx new my-platform # a complete project skeleton
mx add api --recipe rust-api --domain api.localhost # a service with its wisdom included
mx upgrade --diff # review what newer scaffolding would change
mx upgrade # adopt it
Projects don't fork away from the framework: mx upgrade keeps existing projects current with the templates as they improve. It reads the shipped template layout, offers mx's own tooling files for update, never overwrites your compose files or dockerfiles, keeps a .bak beside anything it replaces, and reports "Project is up to date!" on a second run. (This was mech-crate-z5i until its red test went green and joined the gate.)
Four migrations ride with it, all documented at Upgrade:
- Projects now pin
COMPOSE_PROJECT_NAME per project, so containers started under the old shared default are orphaned until you clear them once. make doctor names them.
- Breaking: dev host ports are no longer pinned. Every dev override used to publish a fixed host port, so the second stack died on
Bind for 0.0.0.0:5432 failed: port is already allocated. Ports that tooling dials on demand now publish on host port 0, which Docker allocates free: discover one with docker compose -p <project> port <service> <container-port>, or pin it for a session with DB_HOST_PORT, REDIS_HOST_PORT, NODE_DEBUG_HOST_PORT, METRICS_HOST_PORT, VITE_HOST_PORT or INERTIA_SSR_HOST_PORT. Ports a browser dials from a URL it already holds keep today's number as a default and gain an override: LEPTOS_RELOAD_HOST_PORT (3001), ZOLA_LIVERELOAD_PORT (1024), NGINX_HTTP_PORT / NGINX_HTTPS_PORT, TRAEFIK_HTTP_PORT / TRAEFIK_HTTPS_PORT / TRAEFIK_DASHBOARD_PORT, MX_ROUTER_HTTP_PORT / MX_ROUTER_HTTPS_PORT. Port 24678 is gone outright: astro and nuxt serve HMR over the app's own port, and the router upgrades that websocket same-origin, so the publish was holding a port for nothing. What breaks is a script or GUI profile pointed at localhost:5432 and friends.
- Breaking: Traefik label names carry the compose project.
traefik.http.routers.<service>.* is now traefik.http.routers.${COMPOSE_PROJECT_NAME}-<service>.*, and the same for .services. and .middlewares.. Traefik keeps one router table per machine, so the old unqualified names meant two projects each scaffolding api either lost both routers to Router defined multiple times or, worse, merged silently into one load-balancer pool serving each other's traffic. Hostnames are unchanged by default; the new per-service override is <SERVICE_UPPER>_ROUTER_HOST (SITE_ROUTER_HOST for this repo's own site). What breaks is a script that addressed a label or a dashboard router entry by its bare service name.
- Breaking: container names are no longer fixed. The shipped compose files used to pin
container_name: db, container_name: api and the rest. Container names are a Docker-daemon-wide namespace, so once project names were pinned, two projects both declaring db still failed with . The pins are gone, and Compose derives instead (). names are unchanged: , , the Traefik labels and the graph all address services. What breaks is a script that addressed a by a fixed name, such as or . Use / , or . The one exception is the global router container, which is still : installed once per machine, nothing to collide with.
The cobbled-together everything else
The concerns every team solves badly, differently, per-project — mx standardizes once:
- Environment config: a single documented loading order,
.env.shared → .env.secrets (gitignored) → .env.<service>, all under docker/.config/. Last one wins, and it is that order in every compose file mx ships, application services and backing services alike. Nine files used to disagree; a conformance test over every env_file list in templates/ now holds the rule instead of authoring habit.
- A consistent CLI:
make dev / up / down / logs / sh / ps / build / doctor behave identically in every project. (mx mirrors the same verbs globally.)
- Filesystem discipline: 1:1 host-to-container mounts under
docker/system/ — what you see is what the container sees.
- Documentation:
mx docs compiles project Markdown to PDF/HTML.
- Health:
mx doctor and make doctor check dependencies before they ruin your afternoon.
AI that helps without leaking or wasting
Most "AI-enabled" development bolts a chatbot onto chaos. mx inverts it — make the terrain legible, then arm the agent:
- An MCP server (
mx-mcp-server) exposing 40+ tools: scaffolding (mx_new, mx_add_service), operations (make_dev, make_logs, router controls), project analysis (project_analyze, service_info), and retrieval (rag_*).
- A techniques corpus — RAG over curated engineering docs on pgvector (vector retrieval; a trigram lexical arm exists and is currently weak — tracked as mech-crate-4jw). Agents call
rag_context while planning and implementing, and consult your organization's patterns instead of guessing. The corpus is stored in a Postgres you control — a Neon project or a local container — never a third-party AI vendor's store. Embeddings are computed through any OpenAI-compatible /embeddings endpoint: OpenAI by default; point embedding_base_url at Ollama or LM Studio to keep ingestion and queries fully local.
- A corpus that grows on schedule — this repo's own corpus is maintained by a research skill (
skills/technique-research/) run weekly: it researches a topic, corroborates claims against primary sources, and opens a PR with provenance frontmatter and a full source list. A human merges. Audit trail: RESEARCH_LOG.md.
- Less exploration by construction — identical layouts and stable conventions mean agents don't re-learn project shape per session, and one MCP server understands every mx project.
How it works in 60 seconds
Every mx project honors one folder contract:
project-root/
├── Makefile # the CLI: make dev / up / down / logs / sh ...
├── make/ # make modules (common.mk, dev.mk, ...)
├── scripts/ # shell scripts
├── apps/ # application source code
│ └── <service>/
└── docker/
├── .config/ # env files: .env.shared, .env.secrets, .env.<service>
├── compose/ # atomic per-service compose: <service>.yml + <service>.dev.yml
├── system/ # 1:1 host-to-container mounts
└── dockerfiles/ # one directory per service
That contract is non-negotiable — and it's the point. It's what lets one make dev work everywhere, one router serve everything, and one MCP server understand any project.
Install
curl -fsSL https://mechcrate.dev/install.sh | sh # macOS, Linux; no sudo
# or: brew install unyform-ai/tap/mechcrate
mx --version
mx doctor
mx self-update --check # later: is a newer release out?
The installer downloads the signed tarball for your platform from the
release channel, verifies
its sha256, and installs under ~/.mech-crate with shims in ~/.local/bin.
mx self-update keeps it current (and --rollback undoes an update). The
Homebrew formula installs the same bundle; there mx self-update hands off to
brew upgrade mechcrate. macOS 11+ (Apple silicon and Intel), Linux x86_64
and aarch64, and Windows through WSL 2: the
platform matrix
says what has actually been verified where. Contributors build from a checkout
instead: see Development.
First project
mx router install && mx router up # once per machine
mx new my-app
cd my-app
mx add api --recipe rust-api --domain api.localhost
make doctor # check dependencies
make init # initialize environment
make dev # develop at http://api.localhost
No hand edit in between. make init generates the development credentials the database needs, so make dev reaches a healthy Postgres on a tree that nobody has touched.
Recipes
| Recipe | Status | What it carries |
|---|
astro | ✅ | Full-stack Astro 5 with Vue 3 islands, SSR, shadcn-vue, PrimeVue, global state, Cloudflare deployment |
laravel | ✅ | Laravel 12 + Octane (Swoole) with Filament admin & Inertia.js SSR frontend |
nuxt | ✅ | Nuxt 3 SSR/SSG application with Nitro server, Tailwind CSS |
rust-api | ✅ | Rust API service with Actix-web, SQLx, and hexagonal architecture |
rust-leptos | ✅ | Leptos SSR + Actix-web with shadcn-ui, actor model, PostgreSQL, and Redis |
rust-worker | ✅ | High-performance job worker with Redis pub/sub, PostgreSQL, and local LLM evaluation |
zola | ✅ | Zola static site generator — single binary, no dependencies |
All seven recipes are apply-verified by the test suite (installer round-trip conformance tests), and the assembled dev config of every one of them has to pass docker compose config straight after mx add — a recipe may not reference a compose file it does not ship. Where a recipe declares a framework initializer (astro, nuxt, zola), mx add runs it, so the app arrives as the framework's own starter would make it with mx's wiring layered on top. Pass --opt force_init=true to start that app over: it deletes apps/<service>/ and re-runs the initializer, so it is destructive by design.
A recipe boots unaided. mx new, mx add <svc> --recipe <r>, make dev, with no hand edit in between, for every recipe that brings Postgres with it. scripts/init.sh used to copy .env.secrets.template verbatim and leave DB_USER / DB_PASSWORD / DB_NAME empty, which Postgres refuses to start on. scripts/generate-secrets.sh is now the single generation point every recipe shares: make init runs it, make dev runs make init, and it fills only values that are still empty or still a placeholder, so it never rotates a credential out from under a running database. REDIS_PASSWORD stays blank on purpose, because the shipped Redis wants no auth. make doctor names any key still unset, and any value still holding a ${VAR} reference that Compose cannot resolve from a sibling env file.
mx recipes list and mx recipes info <name> show what's installed; the Recipe Authoring Guide covers writing your own.
The AI layer
mx mcp build # build the MCP server
mx rag ingest # ingest docs/development into the techniques corpus
mx rag status # corpus backend, doc/chunk counts, embedding model
mx rag gaps # mine weak-scoring queries for research topics
mx rag needs a Postgres with pgvector (a local container or a Neon project) and an embeddings key (OPENAI_API_KEY, or any OpenAI-compatible endpoint via embedding_base_url in ~/.mech-crate/config/rag.toml).
The MCP tools group into four families:
- Scaffold —
mx_new, mx_add_service, mx_recipes_list, mx_recipe_info, mx_upgrade
- Operate —
make_dev, make_up, make_down, make_logs, make_shell, mx_router_*
- Understand —
project_analyze, project_detect, service_info, mx_doctor
- Retrieve —
rag_context, rag_search, rag_find_implementation, rag_compare_approaches, rag_get_guidance, rag_health, and friends
An agent with these tools can scaffold a service, start the right subset of the stack, tail its logs, and consult the techniques corpus before writing a line — all through one server you run yourself.
Remote blueprints (optional)
Local recipes are fully self-sufficient — scaffolding, the router, and the CLI require no account. For teams that want organization-connected scaffolding, mx integrates with unyform: mx login links your org, and blueprints generated from your connected repositories become available alongside local recipes. That's the extent of it — an optional cloud source of recipes, not a dependency.
Quality
The test suite gates every release. The three blocking gates — lint, test, coverage — are proven, not assumed: each was demonstrated failing on a deliberately-broken branch before the baseline landed.
make test — the unit + integration gate (cargo-nextest + doc-tests), on every PR and push to mainmake coverage — line coverage against a ratcheting floor (currently 49.5%; BUMP=1 raises it, drops fail CI)make test-known-broken — a TDD lane (a report, not a gate) where every open, testable defect has a red test asserting its fixed behavior; un-ignoring the test is the fix's definition of done (tests/KNOWN_BROKEN.md)make test-e2e — scaffold → router → live URL with real Docker (dispatched workflow)make test-mutants — scheduled mutation testing on the core library (weekly report)
A release tag cannot ship unless its commit passes lint, tests, and coverage — the publish jobs depend on them. We'd rather publicly index our own defects than pretend there aren't any: that's what the known-broken lane is.
Documentation
The docs/development/ directory also holds the techniques corpus itself — 60+ curated engineering docs spanning architecture, concurrency, databases, security, and process. It's readable as documentation and queryable as RAG.
Development
mech-crate/
├── crates/
│ ├── mx-lib/ # core logic
│ ├── mx-cli/ # the `mx` binary
│ └── mx-mcp-server/ # MCP server for AI agents
├── templates/ # project skeleton, recipes, router
└── docs/ # documentation + techniques corpus
make build # debug build
make test # the gate suite
make lint # clippy (-D warnings)
make check # fmt-check + lint + test
make install-local # install to ~/.local/bin
Database-backed tests skip when MX_RAG_TEST_DATABASE_URL is unset, so a laptop without Docker still runs green; CI always supplies the container.
License
Licensed under either of Apache License, Version 2.0 or MIT license at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
