README
¶
Mercator
Modal-style push-to-run for containers, on capacity you control: Mercator starts each workload fast on the warmest machine in your fleet, rents new GPU capacity when none fits, and records what it decided and why.
About · How it compares · Quickstart · Documentation · Contributing · Roadmap
About
Mercator is a compute broker and fleet manager for accelerated workloads. You hand it a container. It compares every place that could take it, machines you already rent and fresh capacity from your GPU provider accounts, books the workload where it should start fastest for the money, launches it, and watches it to a clean exit.
Four terms recur: an offer is a place a run could land (a Docker host, or a RunPod or Vast.ai GPU once connected), a rental is a machine Mercator keeps between runs, your fleet is the rentals you hold, and warmth is how much of a run's image and data a rental already holds locally, which is why warm machines start in seconds.
Every decision is recorded. Three weeks later you can still ask what ran where,
why there, which candidates lost and for what reason, and whether it exited
clean, and get the answer from the event log instead of your memory. That
audited record is the part docker run, and most brokers, cannot give you.
It is one Go process with SQLite as the event log. No Kubernetes, no Slurm, no control plane. The JSON HTTP API, the CLI, and the operator console all come out of the same binary.
Mercator is V1 evaluation-ready, not GA infrastructure. Read known limitations before you rely on it in production.
How it compares
Like Modal, you push a workload with one command and never pick a machine. Unlike Modal, you bring an OCI image rather than Python code, so Mercator does not build or sync your code, and runs land on capacity you control, with no serverless markup and a fleet that stays yours.
Like SkyPilot, Mercator brokers one workload across many providers. Unlike SkyPilot, it does not bootstrap a conda environment first. The container is the environment, so a cold start is an image pull and a warm start skips the layers the machine already holds.
Use it if you are a small team running recurring accelerated jobs, training, batch inference, image generation, on GPUs you rent, and you want Modal's ergonomics without serverless prices or giving up the machines. Recurring is where the fleet pays off: when two jobs declare the same data cache, the second can land on the machine that already synced it.
Quickstart
You need a running Docker daemon. Install the binary with Go, or download one from the releases page:
go install github.com/benngarcia/mercator/cmd/mercator@latest
Start the broker:
mercator serve
Then, in another shell, push a workload and ask why it landed where it did:
mercator run create busybox -- echo hi
mercator run decision
On loopback, serve generates its own token, writes a local CLI context, and
seeds a docker connection when the daemon answers, so nothing else needs
configuring. run create resolves busybox to its digest and platform against
your host, so you pin nothing by hand. run decision returns the offer it
picked, every candidate it rejected, and the reason codes; on a single host the
one offer wins uncontested, and the record fills in as you add offers.
Open the console at http://127.0.0.1:8080 for the
live deployment canvas. For the broker-in-a-container setup and the full
walkthrough with expected output, see
install and configuration and
Docker adapter operation.
Documentation
| Need | Start here |
|---|---|
| Install, start, health checks | install and configuration |
| First local evaluation on Docker | Docker adapter operation |
| CLI commands and environment | CLI reference |
| Deterministic scenarios and replay | Mercator Lab |
| HTTP and OpenAPI routes | OpenAPI overview |
| Workload and run lifecycle | workload and run lifecycle |
| Authentication | authentication |
| Security boundaries | security model |
| What does not work yet | known limitations |
Provider runbooks: RunPod,
Shadeform, Vast.ai.
mercator verify --spec trial.json launches a bounded, real conformance trial
against any of them and returns a sanitized evidence bundle. See
provider conformance. Project process
lives under docs/project and docs/launch.
Contributing and developing
Read CONTRIBUTING.md before opening a pull request. Keep changes narrow, include tests or docs evidence, and update production docs when behavior changes.
go test ./...
go build ./cmd/mercator
scripts/check-open-source-launch.sh
The console is a React app in web/app, built into
web/static and embedded in the binary. Rebuild it with mise run ui. Builds
need no cgo, because Mercator uses the pure-Go SQLite driver
modernc.org/sqlite. Project spaces are covered by the
code of conduct, maintainer decision rules are in
GOVERNANCE.md, and security issues go privately through
SECURITY.md.
Roadmap and status
Mercator runs real workloads end to end and is exercised by a full Go test suite. It is ready to evaluate, and it is not yet ready to be the thing you page someone about.
| # | Step | Status |
|---|---|---|
| 1 | Event-sourced run lifecycle with recorded outcomes and cleanup | ✅ |
| 2 | Placement decisions that record the winner and every rejection | ✅ |
| 3 | Local Docker adapter with real container launch and cleanup | ✅ |
| 4 | GPU provider adapters behind one run contract | 🚧 |
| 5 | Rentals with persisted schedules of queued bookings | ✅ |
| 6 | Live fleet canvas in the console, streamed over SSE | ✅ |
| 7 | Warmth-aware placement: image layers and cache mounts | 🚧 |
| 8 | Multi-node operation: failover, TLS, per-user authorization | ❌ |
The RunPod, Shadeform, and Vast.ai adapters share the Docker adapter's run
contract and each has a runbook and a conformance trial, but they are
experimental: registry credential handling and quota setup are still thin.
Rentals and their schedules are scored today, weighing the runtime queued on a
busy rental against the cost of provisioning fresh capacity; scoring warmth
itself, image layers and cache mounts, is the program being built. The
placement scenario corpus states the decisions
that program must satisfy, and its target scenarios fail CI the moment they
start passing, so the corpus always says where the work stands. Multi-node
operation, the gap between evaluation and production, is tracked in
known limitations and
the roadmap.
License
Mercator is licensed under the Apache License, Version 2.0. See LICENSE and NOTICE.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
mercator
command
|
|
|
mercator-conformance-probe
command
|
|
|
mercator-node
command
Command mercator-node is the Mercator node agent.
|
Command mercator-node is the Mercator node agent. |
|
internal
|
|
|
adapter/shadeform
Package shadeform rents machines through Shadeform (api.shadeform.ai), a GPU marketplace aggregator that fronts ~21 provider clouds behind one API, and bootstraps a Mercator node agent onto each one.
|
Package shadeform rents machines through Shadeform (api.shadeform.ai), a GPU marketplace aggregator that fronts ~21 provider clouds behind one API, and bootstraps a Mercator node agent onto each one. |
|
adapter/vast
Package vast launches Mercator runs on Vast.ai, a marketplace of GPU hosts.
|
Package vast launches Mercator runs on Vast.ai, a marketplace of GPU hosts. |
|
broker
Package broker turns registered connections into live adapters and routes offer collection + run lifecycle across them.
|
Package broker turns registered connections into live adapters and routes offer collection + run lifecycle across them. |
|
capability
Package capability declares the three contracts a backend can implement and the capabilities it negotiates through them.
|
Package capability declares the three contracts a backend can implement and the capabilities it negotiates through them. |
|
capability/capacitytest
Package capacitytest is the bounded set of promises every CapacityProvider keeps, stated once and run against any backend that implements the contract.
|
Package capacitytest is the bounded set of promises every CapacityProvider keeps, stated once and run against any backend that implements the contract. |
|
conformance
Package conformance launches bounded provider trials through Mercator's public lifecycle and proves terminal cleanup.
|
Package conformance launches bounded provider trials through Mercator's public lifecycle and proves terminal cleanup. |
|
credential
Package credential resolves connection credentials from a {source, ref} reference.
|
Package credential resolves connection credentials from a {source, ref} reference. |
|
daemon
Package daemon composes and owns one production Mercator server runtime.
|
Package daemon composes and owns one production Mercator server runtime. |
|
dockertest
Package dockertest hands this machine's one Docker daemon to one test at a time.
|
Package dockertest hands this machine's one Docker daemon to one test at a time. |
|
gpunorm
Package gpunorm maps each provider's native GPU vendor/model strings onto a stable canonical id, so a workload's accelerator requirement matches the same GPU regardless of which provider advertises it.
|
Package gpunorm maps each provider's native GPU vendor/model strings onto a stable canonical id, so a workload's accelerator requirement matches the same GPU regardless of which provider advertises it. |
|
httpapi
Package httpapi provides primitives to interact with the openapi HTTP API.
|
Package httpapi provides primitives to interact with the openapi HTTP API. |
|
keymaterial
Package keymaterial decodes cryptographic keys supplied through configuration.
|
Package keymaterial decodes cryptographic keys supplied through configuration. |
|
node
Package node is the control plane's authority over enrolled Mercator nodes.
|
Package node is the control plane's authority over enrolled Mercator nodes. |
|
node/nodetest
Package nodetest is the shared conformance suite every node.Store must pass.
|
Package nodetest is the shared conformance suite every node.Store must pass. |
|
nodeagent
Package nodeagent is the Mercator node agent: the process that runs on a reusable machine and executes successive workloads there.
|
Package nodeagent is the Mercator node agent: the process that runs on a reusable machine and executes successive workloads there. |
|
nodeapi
Package nodeapi is the transport nodes use to reach the control plane.
|
Package nodeapi is the transport nodes use to reach the control plane. |
|
orchestrator
Redaction for the public event stream.
|
Redaction for the public event stream. |
|
prediction
Package prediction answers what a launch stage will cost from what earlier launches of the same thing really spent.
|
Package prediction answers what a launch stage will cost from what earlier launches of the same thing really spent. |
|
providers
Package providers owns Mercator's production provider catalog.
|
Package providers owns Mercator's production provider catalog. |
|
rental
Package rental is the control plane's authority over the capacity Mercator holds: the leases it has taken, the generations each of them has been through, and the runtime a generation's end retires.
|
Package rental is the control plane's authority over the capacity Mercator holds: the leases it has taken, the generations each of them has been through, and the runtime a generation's end retires. |
|
rental/rentaltest
Package rentaltest is the shared conformance suite every rental.Store must pass.
|
Package rentaltest is the shared conformance suite every rental.Store must pass. |
|
reporting
Package reporting mints and verifies per-run HMAC tokens that authorize a workload to report events for its own run, and nothing else.
|
Package reporting mints and verifies per-run HMAC tokens that authorize a workload to report events for its own run, and nothing else. |
|
runprojection
Package runprojection defines the durable, indexed Run read-model boundary.
|
Package runprojection defines the durable, indexed Run read-model boundary. |
|
scenario
Package scenario owns the versioned Mercator Lab Blueprint catalog and the placement-runner adapter.
|
Package scenario owns the versioned Mercator Lab Blueprint catalog and the placement-runner adapter. |
|
tlsmaterial
Package tlsmaterial loads the certificate and private key a Mercator process terminates TLS with.
|
Package tlsmaterial loads the certificate and private key a Mercator process terminates TLS with. |
|
tlsmaterial/tlsmaterialtest
Package tlsmaterialtest issues throwaway TLS material for tests.
|
Package tlsmaterialtest issues throwaway TLS material for tests. |
|
webauth
Package webauth implements service-local human authentication for the Mercator console: a standard OIDC authorization-code flow against a configurable issuer, an email/domain allowlist, and a signed HTTP-only session cookie.
|
Package webauth implements service-local human authentication for the Mercator console: a standard OIDC authorization-code flow against a configurable issuer, an email/domain allowlist, and a signed HTTP-only session cookie. |