# National Compute documentation

National Compute is burst GPU capacity: nodes join your cluster in real
time when you need them and leave when you don't. You declare how many
GPUs you want and the most you'll pay per GPU-hour; supply is allocated
by price, so you hold capacity while the market clears at or under your
ceiling and are billed what the auction assesses — never above your
ceiling.

[Public Marshall](https://docs.nationalcompute.com/public-marshall.md) offers model chat without sign-in,
with a sponsored allowance per browser visitor. Sign in for saved
sessions, shells and persistent files.

There are three ways to consume capacity:

- **VM clusters** — declare a GPU count and a price ceiling; granted
  nodes are yours over ssh until they are reclaimed or you scale
  down. See the [VM capacity API](https://docs.nationalcompute.com/api/vm-capacity.md).
- **Kubernetes clusters** — a dedicated cluster whose GPU jobs create
  the demand by themselves, each job one request priced in whole nodes
  on the market; the only knob is your price ceiling.
  See [Kubernetes clusters](https://docs.nationalcompute.com/kubernetes.md) and the
  [limit price API](https://docs.nationalcompute.com/api/k8s-bid.md).
- **Public Research** — one whole node at a time for a researcher at
  a public research organization, requested from Marshall and used
  over ssh at a flat rate, outside the auction. See
  [Public Research](https://docs.nationalcompute.com/public-research.md).

## Start here

1. [Burst capacity](https://docs.nationalcompute.com/market.md) — how capacity is allocated: the
   auction, protection windows, and pricing.
2. [Authentication](https://docs.nationalcompute.com/authentication.md) — mint an org API token and make
   your first call.
3. [Billing](https://docs.nationalcompute.com/billing.md) — what the meter measures, and what is never
   billed.
4. [API reference](https://docs.nationalcompute.com/api/index.md) — conventions, endpoints, errors, and
   the machine-readable OpenAPI contracts.

Questions about base load capacity, preemption, pricing, or the access model?
The [FAQ](https://docs.nationalcompute.com/faq.md) covers the ones we hear most.

## For agents

If an AI agent drives your capacity, point it at
[nationalcompute.com/FIRST-JOB.md](https://nationalcompute.com/FIRST-JOB.md)
to run your first job, and at
[nationalcompute.com/llms.txt](https://nationalcompute.com/llms.txt) and
[nationalcompute.com/AGENTS.md](https://nationalcompute.com/AGENTS.md)
for orientation — pages served unauthenticated for exactly that purpose.
The console's Getting Started page carries the prompt to paste. The
OpenAPI contracts are unauthenticated too, so an agent can discover the
wire before it holds a token:

- [`/api/vm/openapi.json`](https://nationalcompute.com/api/vm/openapi.json)
  — the VM capacity contract
- [`/api/k8s/openapi.json`](https://nationalcompute.com/api/k8s/openapi.json)
  — the Kubernetes limit price contract
- [`/api/billing/openapi.json`](https://nationalcompute.com/api/billing/openapi.json)
  — the billing records contract

An agent that speaks MCP (Model Context Protocol) takes the surface as
tools instead of routes. The hosted [MCP server](https://docs.nationalcompute.com/api/mcp.md) at
`https://nationalcompute.com/mcp` carries market data, capacity, limit
prices, billing, hardware metrics and server-side Kubernetes access
behind one OAuth sign-in, with no token to mint. Claude Code, Codex and
Cursor add it with one line of configuration.

The starter recipes FIRST-JOB.md walks through are a catalog at
[`access.nationalcompute.com/first-job/`](https://access.nationalcompute.com/first-job/):
each recipe's cluster kind, category, description, default file and
vendor variants, as JSON, next to the manifests themselves.

A program reads these pages at `nationalcompute.com/docs/<page>`, no
token needed, the same paths as this site — or as markdown here: a
page's URL minus the trailing slash, plus `.md` (`/market/` becomes
`/market.md`), is its source with every link made absolute. Every HTML
page names that form in a `<link rel="alternate" type="text/markdown">`.
[llms.txt](https://docs.nationalcompute.com/llms.txt) indexes every page
that way, with a one-line description each;
[llms-full.txt](https://docs.nationalcompute.com/llms-full.txt) is the
whole site in one file; [sitemap.xml](https://docs.nationalcompute.com/sitemap.xml)
lists the pages.

The specs are the authority whenever these pages and a spec disagree.