Your first InferCrane request

In this guide you will start the complete control and request path, call a stable model endpoint, and inspect the durable state behind it. No GPU or cloud account is required.

The local stack uses GPU-free fake vLLM workers. It proves application and lifecycle behavior, not model quality, GPU performance, or real-provider compatibility.

Local proof and teammate access are two separate workflows. The quickstart binds a loopback fixture with the public development credential infercrane; sharing, tunneling, or port-forwarding that endpoint is unsupported. To serve a teammate without provisioning new GPU capacity, connect an already-operated upstream in a customer-owned TLS environment and issue a tenant-scoped credential. Follow Share a development endpoint safely; do not reuse the local fixture or its credential.

Fast proof: one command

From a repository checkout, one command runs the local product proof and cleans up its isolated Docker project:

make demo

The GPU-free proof connects a fixture endpoint because it cannot provision a real model. It sends and inspects a request, creates an intentionally unready candidate, records a deterministic Release Guard rejection, verifies the active revision did not change, rejects the candidate, and removes all temporary state. This proves the application and lifecycle loop locally; it does not replace the model-to-endpoint deployment path or claim GPU/provider qualification.

Choose either the one-command proof above or the manual tour below. make demo already starts an isolated stack, exercises the workflow, and tears that stack down; you do not need to run both paths.

Manual tour: inspect each step

Prerequisites

Git, Python 3, cURL, and jq
Docker with Compose v2 and a reachable engine
Port 18000 available

Clone InferCrane

Clone the public repository and enter the checkout:

git clone https://github.com/infercrane/infercrane.git
cd infercrane

Start the local stack

docker compose up --build -d
curl -fsS http://127.0.0.1:18000/readyz

If Docker reports that port 18000 is already allocated, identify the owner before changing anything:

docker compose ps
lsof -nP -iTCP:18000 -sTCP:LISTEN

If it is an earlier InferCrane stack from this checkout, docker compose down stops it without deleting the named PostgreSQL volume, then retry up. If another application owns the port, leave it alone and choose a different host port:

export INFERCRANE_DEV_PORT=18001
docker compose up --build -d
curl -fsS "http://127.0.0.1:${INFERCRANE_DEV_PORT}/readyz"

Replace 18000 with the selected port in the remaining manual-tour URLs. Do not use docker compose down --volumes unless you intentionally want to erase local InferCrane state.If the port opens but /readyz does not become healthy, inspect the existing containers before retrying setup:

docker compose ps
docker compose logs --tail 100 postgres
docker compose logs --tail 100 infercrane
curl -i "http://127.0.0.1:${INFERCRANE_DEV_PORT:-18000}/livez"
curl -i "http://127.0.0.1:${INFERCRANE_DEV_PORT:-18000}/readyz"

/livez proves the process is running; /readyz additionally requires PostgreSQL. Fix the first concrete container, configuration, or migration error, then rerun docker compose up --build -d. That retry reuses the same named volume and does not create provider resources. Never delete the PostgreSQL volume, edit migration-ledger rows, or start a paid deployment to repair a local readiness failure. If logs show a migration checksum, gap, or newer-schema error, stop and follow Upgrade and compatibility rather than retrying destructively.The stack includes PostgreSQL, InferCrane, two fake workers, and a development router. The development API key is infercrane; production mode rejects that default.

Send a request

The CLI and cURL examples require no language package. For the Python example, install the official OpenAI client in your active virtual environment with python -m pip install openai.

docker compose exec infercrane \
  infercrane request qwen-prod --message "Explain durable operations in one sentence."

curl -fsS http://127.0.0.1:18000/v1/chat/completions \
  -H 'Authorization: Bearer infercrane' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "qwen-prod",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:18000/v1",
    api_key="infercrane",
)

response = client.chat.completions.create(
    model="qwen-prod",
    messages=[{"role": "user", "content": "Hello"}],
)
print(response.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "http://127.0.0.1:18000/v1",
  apiKey: "infercrane",
});

const response = await client.chat.completions.create({
  model: "qwen-prod",
  messages: [{ role: "user", content: "Hello" }],
});
console.log(response.choices[0].message.content);

Add --stream to the CLI request to print response text as chunks arrive.

Inspect what happened

docker compose exec infercrane infercrane status qwen-prod
docker compose exec infercrane infercrane events qwen-prod
docker compose exec infercrane infercrane explain qwen-prod

These commands use the authenticated control-plane API. Public CLI workflows never connect directly to PostgreSQL.

Open the terminal operations view

docker compose exec infercrane infercrane ui

The terminal workspace reads the same durable control API and can be closed without cancelling operations. InferCrane also operates the browser console at console.infercrane.com; see Operations console for its source and deployment boundary.

Stop the stack

docker compose down

This preserves PostgreSQL data. Add --volumes only when you intend to delete the local state.

Choose your next path

Deploy a real model

Plan provider and runtime choices before creating billable capacity.

Connect an endpoint

Observe an existing vLLM, LiteLLM, or OpenAI-compatible endpoint first.

Share with a teammate

Use a separate TLS-protected environment and scoped credentials; never expose the local fixture.

Connect a model API

Understand the model

Learn endpoints, environments, serving plans, deployments, and revisions.

Before creating real infrastructure

Do not expose the local fixture as a team service

The Compose quickstart binds a development control plane and uses the known development credential infercrane. It is not a supported shared-access mode. Do not port-forward it, publish it through a tunnel, send the credential to a teammate, or treat loopback fake workers as a shared model. To collaborate without creating paid infrastructure, keep each developer’s fixture local and share the same version-controlled DeploymentSpec and qualification evidence. If the team needs one shared endpoint, use a customer-owned, TLS-protected environment with tenant-scoped credentials and network policy. Follow Share a development endpoint safely for the complete deployment, credential, qualification, request, and revocation path. An existing in-region vLLM/SGLang service can be connected observe-only without provisioning capacity; see Connect existing inference. Otherwise stop after plan until a provider budget and exact real-environment qualification are approved. The local fixture cannot be promoted into a shared environment: its workers do not contain the model, runtime, accelerator, or provider settings of a real deployment. Recreate the intended combination explicitly and stop before mutation if its evidence is incomplete:

infercrane integrations --output json
infercrane models inspect MODEL_CATALOG_NAME --output json
infercrane plan MODEL_REPOSITORY \
  --cloud PROVIDER \
  --gpu ACCELERATOR \
  --output json

The three results must agree on the adapter, runtime/version, compute mode, immutable model, accelerator, environment, and required real-system qualification. The local smoke result is only control-flow evidence and does not satisfy any missing row. Follow the selected provider guide and exact-combination policy before deploy. Install the public-beta CLI with Homebrew or download a matching archive from the v1.0.0-rc.1 prerelease:

brew install infercrane/tap/infercrane
export INFERCRANE_API_KEY='ISSUED_CONTROL_PLANE_CREDENTIAL'
infercrane init --url https://infercrane.example
infercrane auth status
infercrane doctor --cloud
infercrane plan Qwen/Qwen3-8B --cloud runpod --gpu L40S

plan is side-effect free. A real deploy can create billable resources, so check provider setup and compatibility and qualification first. Adapter registration does not prove that an exact model, runtime, GPU, and provider combination has passed real-infrastructure qualification.

Start here

Deploy and connect

Operate

Evidence and decisions

Quickstart

Your first InferCrane request

Fast proof: one command

Manual tour: inspect each step

Prerequisites

Choose your next path

Deploy a real model

Connect an endpoint

Share with a teammate

Connect a model API

Understand the model

Before creating real infrastructure

Do not expose the local fixture as a team service

​Your first InferCrane request

​Fast proof: one command

​Manual tour: inspect each step

​Prerequisites

​Choose your next path

Deploy a real model

Connect an endpoint

Share with a teammate

Connect a model API

Understand the model

​Before creating real infrastructure

​Do not expose the local fixture as a team service

Your first InferCrane request

Fast proof: one command

Manual tour: inspect each step

Prerequisites

Choose your next path

Before creating real infrastructure

Do not expose the local fixture as a team service