Public Container Images & Quickstart

dgem publishes official, public container images to Google Artifact Registry open to all users globally (allUsers read permissions). No Google Cloud account, IAM credentials, or service account keys are required to pull them.

1. Published Container Images

Image Tag	Digest	Compressed Size	Weights Delivery	Recommended Use Case
`dgem:v0.3.7` (also `:latest`)	`sha256:6153fe707962...`	`~10 GB`	Downloads the public weights from Hugging Face at boot, or mounts them (Cloud Storage / local path)	Cloud Run GPU (recommended), Vertex AI, GCE VMs, local Docker
`dgem-weights:v0.3.7` (also `:latest`)	`sha256:5593d908c858...`	`~26 GB`	NVFP4 weights baked in at `/opt/dgemma/weights`; no download at boot, but a large pull (~8–12 minutes on a fresh Cloud Run instance)	Offline or air-gapped hosts

Both images were validated side by side with the production serving image (API contract, latency, 0 errors at 32 concurrent clients) before publishing; see the image parity run and Deploy on Cloud Run §7 for cold-start numbers. Pin by digest in production; :latest moves. Releases and what changed: CHANGELOG. A running container reports its release in /health (version, revision, vllm_commit).

For deploying to Google Cloud Run GPU or Vertex AI Dedicated Endpoints, see Deploy on Cloud Run or Production on Vertex AI.

Pulling the Image

# Pull lean image (pinned digest):
docker pull us-central1-docker.pkg.dev/dgem-diffusiongemma/dgem/dgem:v0.3.7@sha256:6153fe7079620d7ad608d8409ce55b295c362de808fce2fc28368cfb6b64c19f

# Or pull self-contained image with pre-baked NVFP4 weights (pinned digest):
docker pull us-central1-docker.pkg.dev/dgem-diffusiongemma/dgem/dgem-weights:v0.3.7@sha256:5593d908c85879c76bb942700cdac9ce83a87a290ebd8e301d8715b7bbc7acb6

2. Running on Your Own GPU Host

GPU requirements. The images serve the 4-bit NVFP4 checkpoint (~18 GiB of weights):

GPU	Status	Host RAM
NVIDIA RTX PRO 6000 (Blackwell, 48 GB)	Recommended; tested and used in production (native FP4, vision tower on)	80 GiB
NVIDIA L4 (Ada, 24 GB)	Works, about 3× slower per request	32 GiB with `DISABLE_MM=1`; 64 GB with the vision tower on
Other NVIDIA GPUs (Hopper, Ampere, other Blackwell cards)	Not tested with these images	—

On an untested GPU, verify the install against the known benchmark ranges before relying on it: Evaluate dgem on your own GPU.

A. Decision Index Certified Mode (`ROLE=decision-index`)

Starts dgem systemone serve on port 8080 (with multi-slot canvas batching and 2-stage bracket tournament routing) in front of internal structured_server.py on port 8081 and vLLM on port 8000:

docker run --gpus all \
  -p 8080:8080 \
  -e ROLE=decision-index \
  -e TEMPERATURE=1.0 \
  us-central1-docker.pkg.dev/dgem-diffusiongemma/dgem/dgem:v0.3.7@sha256:6153fe7079620d7ad608d8409ce55b295c362de808fce2fc28368cfb6b64c19f

Once running and healthy (curl http://localhost:8080/health), run the official upstream Decision Index pipeline:

python -m decision_index pipeline \
  --engine http \
  --option base_url=http://127.0.0.1:8080 \
  --option model=dgem \
  --out runs/dgem-0.2.1

B. Standard OpenAI & Decision Studio Mode (`ROLE=default`)

Serves /v1/chat/completions (OpenAI format), /v1/systemone pass-through, and /health:

docker run --gpus all \
  -p 8080:8080 \
  us-central1-docker.pkg.dev/dgem-diffusiongemma/dgem/dgem:v0.3.7@sha256:6153fe7079620d7ad608d8409ce55b295c362de808fce2fc28368cfb6b64c19f

Then point dgem CLI, Decision Studio, or MCP at http://127.0.0.1:8080/v1:

# Single decision via CLI
./bin/dgem decide -u http://127.0.0.1:8080/v1 \
  -t templates/support_triage.json.tmpl \
  -v 'ticket=Emergency database outage' --stats

# Full JevBench v1.4 evaluation with leaderboard comparison
./bin/dgem bench-jev -u http://127.0.0.1:8080/v1 --endpoint-kind gpu --compare-leaderboard

3. Environment Variables & Runtime Configuration

Variable	Default	Purpose
`ROLE`	`default`	`decision-index` (starts wide-canvas tournament adapter on `PORT`) or `default` (direct serving).
`PORT`	`8080`	External HTTP port to bind.
`TEMPERATURE`	`1.0`	Post-hoc slot logit temperature scaling $T^*$ ( $1.0$ unscaled for official submissions).
`API_KEY`	`""` (open)	Optional secret key. When set, all incoming requests must supply `Authorization: Bearer <key>`.
`DGEM_SERVER_KEY`	`""` (off)	Service-to-service secret. When set, every `POST` needs header `X-DGem-Key` with one of the keys (comma-separated, to rotate: `new,old`); `GET /health` stays open. Use it when the serving image is reachable by more than your own services, for example a Vertex dedicated endpoint: give it to services that call the server (your gateway, batch jobs), not to people, and route people through an authenticated gateway so access is tracked. Callers send it when their own `DGEM_SERVER_KEY` is set (`dgem` CLI and gateway, `dgem systemone serve`, `scripts/matrix`). Unlike `API_KEY` it works on Vertex and Cloud Run, where `Authorization` carries the Google token.
`DGEM_IMAGE_URLS`	`deny`	Whether the server lets vLLM fetch http(s) image URLs from requests. `deny` accepts images only as data: URIs or multipart uploads and answers 400 to a URL: the serving image has network egress, so a URL could be steered to the metadata server or internal hosts. The `dgem` CLI and gateway fetch URLs themselves and send data: URIs, so they work with `deny`. `allow` restores the old behaviour for trusted callers only.
`CANVAS`	`128`	Served diffusion canvas length in tokens.
`MODEL`	`/mnt/gcs/dgemma`	Weights path. Baked weights at `/opt/dgemma/weights` are used automatically; a mounted path is used if it has `config.json`; otherwise weights are staged from `DGEM_WEIGHTS_URI` (a `gs://` URI) or downloaded from `MODEL_HF`.
`MODEL_HF`	`nvidia/diffusiongemma-26B-A4B-it-NVFP4`	Hugging Face repo downloaded when no weights are baked, mounted or staged.
`DEFAULT_SAMPLES`, `MAX_INFLIGHT`	`1`, `8`	Samples for schemas without `samples`; decisions processed at once (the rest queue).
`MAX_MODEL_LEN`	`4096` (image); deploy scripts set `8192` on RTX PRO 6000	Longest prompt plus answer, in tokens. Longer prompts are refused. At 8,192 short-prompt accuracy and latency match 4,096 (EXP-20); 32,768 answers far longer prompts but is still being validated under load.
`DEFAULT_ISOLATE`, `ISOLATE_AUTO_MAX`, `ISOLATE_MAX_QUESTIONS`	`auto`, `3`, `8`	Which questions get a read of their own when a request doesn’t say: `auto` (yes/no questions in text requests of 2–3 questions with at least 2 yes/no; from v0.3.0), `none` (one joint read, the behaviour before v0.3.0), `noul` (every yes/no question, requests of 2–8 questions) or `all`. A request can set `"isolate"`, and a question `"alone": true/false`. See reading yes/no questions alone.
`HTTP_IDLE_TIMEOUT`	`120`	Seconds before an idle keep-alive connection is closed (0 = never).
`DEFAULT_LABELS`	`az`	Labels for `choice` options in requests without `labels`: `az` (A–Z, at most 26 options), `az_aa` (A–Z then AA–AZ, at most 52) or `az_lower` (A–Z then a–z, at most 52, requests of up to 10 questions only). Experimental beyond `az`; keep the default unless you have measured otherwise.
`DEFAULT_SEED_TOKEN`	`random`	What sits at each answer position before the read, for requests without `seed_token`: `random` (a seeded random token, so reads vary with the seed) or `fixed` (the padding token; reads stop depending on the seed). Under test in PROP-32; keep `random` until it’s decided.
`DEFAULT_LAYOUT`	`document_first`	Prompt layout for requests without `layout`: `document_first` (the state, then the questions) or `schema_first` (the questions as the system prompt, the behaviour before v0.2.0).
`DISABLE_MM`	`0`	`1` disables the vision tower (required on an L4 with 32 GiB host RAM).

4. Container Lineage & Provenance

Base Image: Official vllm/vllm-openai:nightly pinned by commit and digest (vllm-project/vllm:main commit a9eafde59cb).
PR Inclusions: Upstream PR #57250 (“[Core] structured generation mode for DiffusionGemma”) and PR #58216 (“[Perf] constrained reads”) are natively included in the base image. Structured mode lets the server send its own seeded canvas and ask for a read-only denoise step with logprobs for chosen token ids (logprob_token_ids); constrained reads compute the output layer and sampler over those label ids only, which gives the same answer with about a quarter less GPU time per read. vLLM accepts at most 128 such ids per request.
Patches: Pinned in deploy/cloudrun/server/dgem.patch and tracked via deploy/cloudrun/server/UPSTREAM.