diff --git a/datumctl/compute/building-images.mdx b/datumctl/compute/building-images.mdx
new file mode 100644
index 0000000..9f3f3f3
--- /dev/null
+++ b/datumctl/compute/building-images.mdx
@@ -0,0 +1,94 @@
+---
+title: "Building images"
+sidebarTitle: "Building images"
+description: "Turn a Dockerfile into an image Datum Compute can run, check it for compatibility, and publish it with datumctl compute build."
+---
+
+`datumctl compute build` packages a Dockerfile and build context into an image, and optionally publishes it. Point it at the same Dockerfile you already use for a normal container — no Compute-specific syntax required.
+
+```bash
+datumctl compute build .
+```
+
+Compute doesn't run that image as a normal container — it boots it as a unikernel, which is what gives Compute VM-level isolation between workloads at container-like density and cold-start speed. `build` packages your Dockerfile into the artifact that runtime boots from, and validates it against unikernel requirements as part of the same step — so a missing shared library or the wrong architecture shows up as a build-time error instead of a workload that never comes up.
+
+
+ `build` needs a BuildKit backend to run: Docker Desktop or Docker Engine with BuildKit enabled (the default on modern installs), a standalone `buildkitd`, or `BUILDKIT_HOST` pointing at one.
+
+
+With no `--output`, this is a **local debug build**: it packages the image so you can confirm it builds successfully, without writing or publishing anything. Once you're ready to deploy it, add `--output` or move on to [deploying workloads](/datumctl/compute/deploying-workloads).
+
+## Choosing a Dockerfile
+
+By default, `build` looks for `Dockerfile.datum` in the build context and falls back to `Dockerfile` if that file does not exist — a convenient way to keep a Compute-specific variant alongside your normal one without extra flags. Use `-f` to point at a Dockerfile anywhere else:
+
+```bash
+# Use a Dockerfile in a non-default location
+datumctl compute build -f ./deploy/Dockerfile .
+
+# Pass build-time variables used by ARG instructions
+datumctl compute build --build-arg VERSION=1.2.3 .
+
+# Package a specific stage of a multi-stage Dockerfile (default: the final stage)
+datumctl compute build --target production .
+```
+
+## Writing the output somewhere
+
+`--output` (`-o`) accepts three kinds of destination:
+
+| Destination | Example |
+|-------------|---------|
+| Registry reference | `--output ghcr.io/acme/api:latest` |
+| OCI archive (`.tar`) | `--output ./compute-image.tar` |
+| OCI layout directory | `--output ./compute-image` |
+
+```bash
+# Publish straight to a registry
+datumctl compute build --push --output ghcr.io/acme/api:latest .
+
+# Write a portable OCI archive instead
+datumctl compute build --output ./compute-image.tar .
+```
+
+
+ When `--output` is a registry reference, `build` asks for confirmation before pushing. Pass `--push` to skip that prompt — required in CI, where there is no terminal to confirm on.
+
+
+## Checking compatibility before you package it
+
+`--analyze` inspects the built entrypoint for the kind of problem that only shows up once Compute's unikernel runtime tries to boot the image — a binary built for the wrong architecture, a startup script whose interpreter is missing, or a shared library the final stage never copied in:
+
+```bash
+datumctl compute build --analyze .
+```
+
+Where a fix is a mechanical Dockerfile edit, the finding shows exactly what to change:
+
+```text
+error[missing-libs]: /app/server requires 1 runtime file that is not present in the image
+ --> Dockerfile:8
+ | Copy the missing shared library into the final stage
+ | - COPY --from=build /app /app
+ | + COPY --from=build /app /app
+ | + COPY --from=build /lib/libc.so.6 /lib/libc.so.6
+```
+
+Reach for `--fix` once you're ready to apply changes like that automatically — it edits the selected Dockerfile in place and rebuilds. `--fix` implies `--analyze`, and only ever applies safe, exact-line edits — it will never restructure your Dockerfile.
+
+```bash
+datumctl compute build --fix .
+```
+
+## Inspecting a published image
+
+`build inspect ` is a diagnostic for an image that already exists in a registry — useful when a deployment isn't starting and you want to confirm the image itself is the problem before looking at the workload. It reports the same kind of compatibility findings as `--analyze`, plus the packaged filesystem and startup configuration Compute will boot from. Add `--extended` for additional OCI metadata — the image index, manifest digest, and layer count. Inspection never downloads the packaged filesystem layer itself, so it stays fast even against a large image.
+
+```bash
+datumctl compute build inspect ghcr.io/acme/api:1.4.2
+```
+
+## Next steps
+
+- `datumctl compute build --help` and `datumctl compute build inspect --help` for the full flag reference.
+- [Deploying workloads](/datumctl/compute/deploying-workloads) — take a published image and run it as a workload.
diff --git a/datumctl/compute/deploying-workloads.mdx b/datumctl/compute/deploying-workloads.mdx
new file mode 100644
index 0000000..016ddc5
--- /dev/null
+++ b/datumctl/compute/deploying-workloads.mdx
@@ -0,0 +1,86 @@
+---
+title: "Deploying workloads"
+sidebarTitle: "Deploying workloads"
+description: "Deploy a container image as a workload with datumctl compute deploy, and check its health with datumctl compute workloads."
+---
+
+`datumctl compute deploy` takes a container image and runs it as a workload across one or more cities. It supports two ways of describing what to deploy — flags, or a manifest file for the declarative form — and both converge on the same underlying workload.
+
+```bash
+datumctl compute deploy api \
+ --image=ghcr.io/acme/api:1.4.2 \
+ --city=DFW,IAD \
+ --min=2 \
+ --port=8080
+```
+
+
+ `--image` must point to an image produced by `datumctl compute build`, not a standard OCI image from `docker build` — see [Building images](/datumctl/compute/building-images). Compute boots workloads as unikernels, which requires the packaged filesystem and startup metadata `compute build` adds during packaging.
+
+
+If a workload named `api` doesn't exist yet, this creates it with one placement (`default`) spanning both cities, each running at least 2 instances. Run the same command again with a new `--image` and it updates the existing workload instead — `deploy` is create-or-update, the same idempotent shape as `datumctl apply` elsewhere in the CLI.
+
+## Flags at a glance
+
+| Flag | Meaning |
+|------|---------|
+| `--image` | Container image to deploy, required with the flags path. |
+| `--city` | One or more city codes to deploy to, comma-separated (`DFW,IAD`). |
+| `--min` | Minimum instances per city (default `1`). |
+| `--instance-type` | Instance type (default `datumcloud/d1-standard-2`). |
+| `--port` | Port to expose on the workload, optional. |
+| `-y`/`--yes` | Skip the confirmation prompt — needed in scripts and CI. |
+
+
+ `deploy` needs a network to attach the workload to. If none exists yet in the project, it offers to create a minimal one, with IP addresses assigned automatically, on your behalf — pass `-y` to accept that automatically in a non-interactive run.
+
+
+## Watching the rollout
+
+`deploy` waits and prints progress as instances come up, the same view `datumctl compute rollout` shows on demand — see [Operations](/datumctl/compute/scaling-and-operations). Ctrl-C detaches from the watch without canceling anything; the rollout keeps going in the background; run `datumctl compute rollout api` any time to reattach.
+
+## Deploying from a manifest
+
+A flag-based deploy writes a `workload.yaml` in the current directory after it succeeds — the same `Workload` resource the flags produced, expressed as YAML. Point `-f` at a manifest to deploy from it instead of flags:
+
+```bash
+datumctl compute deploy -f workload.yaml
+```
+
+This path shows a human-readable diff of what would change before touching anything, then asks for confirmation (skip it with `-y`):
+
+```bash
+datumctl compute deploy -f workload.yaml -y
+```
+
+
+ A manifest is the only way to reach configuration the flags don't expose — a second placement, additional ports, or environment variables. Edit the generated `workload.yaml` (or write one from scratch) and apply it with `-f`.
+
+
+## Checking workload health
+
+`datumctl compute workloads` lists every workload in the project, with per-city ready counts rolled into a single health summary:
+
+```bash
+# List everything
+datumctl compute workloads
+
+# Only workloads that are degraded right now
+datumctl compute workloads --health=degraded
+
+# Only workloads with a placement in one city
+datumctl compute workloads --city=DFW
+```
+
+Health is one of `available`, `degraded`, `progressing`, or `unknown`. For the full picture on a single workload — its container spec, scale settings, and per-city ready/desired counts together — use `describe`:
+
+```bash
+datumctl compute workloads describe api
+```
+
+## Next steps
+
+- `datumctl compute deploy --help` and `datumctl compute workloads --help` for the full flag reference.
+- [Operations](/datumctl/compute/scaling-and-operations) — restart, watch a rollout, and inspect individual instances.
+- [Destroying workloads](/datumctl/compute/destroying-workloads) — tear a workload down when you're done with it.
+- [Building images](/datumctl/compute/building-images) — build and publish the image you're deploying here.
diff --git a/datumctl/compute/destroying-workloads.mdx b/datumctl/compute/destroying-workloads.mdx
new file mode 100644
index 0000000..28c61e2
--- /dev/null
+++ b/datumctl/compute/destroying-workloads.mdx
@@ -0,0 +1,31 @@
+---
+title: "Destroying workloads"
+sidebarTitle: "Destroying workloads"
+description: "Delete a workload and every instance it created with datumctl compute destroy."
+---
+
+`datumctl compute destroy` removes a workload and every instance it created, across every city it was placed in:
+
+```bash
+datumctl compute destroy api
+```
+
+Before deleting anything, it prints a summary of what's about to go — the number of placements, the cities involved, and total minimum replicas — then asks for confirmation. Pass `-y`/`--yes` to skip the prompt in scripts and CI:
+
+```bash
+datumctl compute destroy api -y
+```
+
+
+ Unlike `datumctl delete` elsewhere in the CLI, `destroy` has no `--dry-run` and there's no `diff` equivalent to preview it. The confirmation prompt is your only checkpoint — read the summary it prints, or check the workload yourself first:
+
+ ```bash
+ datumctl compute workloads describe api
+ ```
+
+
+## Next steps
+
+- `datumctl compute destroy --help` for the full flag reference.
+- [Deploying workloads](/datumctl/compute/deploying-workloads) — redeploy the workload later from the same manifest or image.
+- [Operations](/datumctl/compute/scaling-and-operations) — restart or check instances before you decide to remove a workload altogether.
diff --git a/datumctl/compute/overview.mdx b/datumctl/compute/overview.mdx
new file mode 100644
index 0000000..2501321
--- /dev/null
+++ b/datumctl/compute/overview.mdx
@@ -0,0 +1,143 @@
+---
+title: "Compute"
+sidebarTitle: "Overview"
+description: "Deploy and manage containerized workloads on Datum Cloud with the datumctl compute plugin."
+---
+
+
+ Compute is coming soon and is not yet generally available.
+
+
+`datumctl compute` deploys a container image as a **workload** running across one or more Datum Cloud cities, then gives you the day-to-day commands to scale, restart, and tear it down. It is a first-party plugin rather than a built-in command — install it once and its commands behave exactly like the rest of the CLI.
+
+```bash
+datumctl plugin install compute
+datumctl compute --help
+```
+
+
+ New to plugins? [Using plugins](/datumctl/plugins/using-plugins) covers installation, upgrades, and how a plugin inherits your active context and credentials. Not installed `datumctl` itself yet? Start with the [Quickstart](/datumctl/quickstart).
+
+
+## Core concepts
+
+A handful of terms recur across every `compute` command:
+
+| Term | Meaning |
+|------|---------|
+| **Workload** | The thing you deploy — a container image plus its runtime configuration (ports, env, instance type) and one or more placements. |
+| **Placement** | A named group of cities and a scale policy (minimum replica count) within a workload. `deploy` from flags creates a single placement named `default`. |
+| **City** | A short code identifying a Datum Cloud location a workload can run in, for example `DFW` or `IAD`. |
+| **Instance** | One running copy of a workload's container in one city. A placement with `--min=2` across two cities produces four instances. |
+
+`compute` is project-scoped: every command reads `--project` (or your active context's project, injected automatically — see [Contexts & scoping](/datumctl/contexts-and-scoping)). There is no organization-level view and no `--namespace` flag; all compute resources live in the project's `default` namespace.
+
+## Requesting access
+
+Compute is a gated service. The first time you run a command that needs it, `datumctl` checks whether your project is entitled to use Compute:
+
+
+
+ No request has been made yet. On an interactive terminal, the gate offers to submit one for you.
+
+
+ A request is awaiting a manual decision by the service provider. Latency is unbounded.
+
+
+ The project is entitled — every `compute` command runs normally.
+
+
+ The provider rejected the request (or later revoked it). Recovery is submitting a new request.
+
+
+
+### The automatic gate
+
+Run any gated command — `deploy`, `workloads`, `instances`, and so on — without access, and on a TTY `datumctl` prompts you inline:
+
+```bash
+datumctl compute deploy api --image=ghcr.io/acme/api:1.4.2 --city=DFW --min=1
+```
+
+`datumctl` checks if Compute is enabled for the project, and — if not — asks whether to request access; on confirmation, it submits the request and waits briefly to see whether the platform approves it immediately or the request needs manual review.
+
+Decline, and nothing is submitted — run `datumctl compute access request` yourself whenever you're ready. In a non-interactive shell (CI, a script, or a piped command), the gate never prompts; it fails immediately and tells you which command to run.
+
+### Checking and requesting access explicitly
+
+Use `datumctl compute access` to check the current state directly, and `access request` for more control over submitting one than the automatic prompt gives you:
+
+```bash
+# Show the current access state
+datumctl compute access
+
+# Submit a request with a justification, useful for the provider's review
+datumctl compute access request --message="Onboarding the api service"
+
+# Submit and block until the platform's first decision (or --timeout elapses)
+datumctl compute access request --wait
+
+# A denied or revoked request is terminal — --renew deletes it and submits fresh
+datumctl compute access request --renew
+```
+
+`datumctl compute access` prints the state, the platform's explanation, and — when there's a next step — the exact command to run:
+
+```text
+Service: Compute (compute.datumapis.com)
+Project: acme-prod
+Status: Not requested
+ This service is not enabled for this project.
+
+Request access with: datumctl compute access request
+```
+
+Add `-o json` or `-o yaml` to script against the state instead of parsing prose.
+
+## Checking quota
+
+Once active, `datumctl compute quota` shows how much of your project's compute allotment is used:
+
+```bash
+datumctl compute quota
+```
+
+```text
+Quota for project acme-prod
+
+RESOURCE UNIT LIMIT USED AVAILABLE USAGE
+Workloads workloads 10 3 7 [######--------------] 30%
+Instances instances 50 12 38 [#####---------------] 24%
+vCPUs vCPUs 32 8 24 [#####---------------] 25%
+Memory MiB 65536 16384 49152 [#####---------------] 25%
+```
+
+Pass `--constrained` to show only the resource types that are currently at their limit — the fastest way to check whether a stalled rollout is a quota problem:
+
+```bash
+datumctl compute quota --constrained
+```
+
+## Find your way around
+
+
+
+ Turn a Dockerfile into an image Compute can run, and check compatibility before you deploy.
+
+
+ Deploy a workload from flags or a manifest, and read back its health across cities.
+
+
+ Roll restarts, watch a rollout, and debug individual instances.
+
+
+ Tear down a workload and every instance it created.
+
+
+
+## Related
+
+- `datumctl compute --help` and `datumctl compute --help` for the full flag reference.
+- [Using plugins](/datumctl/plugins/using-plugins) — how the `compute` plugin is installed, upgraded, and trusted.
+- [Contexts & scoping](/datumctl/contexts-and-scoping) — how the project a `compute` command runs against is resolved.
+- [Output formats & scripting](/datumctl/output-and-scripting) — `-o json`/`-o yaml` patterns that apply across `compute` subcommands.
diff --git a/datumctl/compute/scaling-and-operations.mdx b/datumctl/compute/scaling-and-operations.mdx
new file mode 100644
index 0000000..56f17b9
--- /dev/null
+++ b/datumctl/compute/scaling-and-operations.mdx
@@ -0,0 +1,64 @@
+---
+title: "Operations"
+sidebarTitle: "Operations"
+description: "Restart, roll out, and inspect individual instances of a running workload with datumctl compute."
+---
+
+Once a workload is deployed, these are the commands for day-to-day operation: restarting instances, watching a rollout progress, and drilling into a single instance when something isn't right.
+
+## Restarting
+
+`datumctl compute restart` triggers a rolling restart — instances are replaced without changing the image or configuration, useful for picking up an external change like a secret rotation:
+
+```bash
+# Restart every instance of the workload
+datumctl compute restart api
+
+# Restart only the instances in one city
+datumctl compute restart api --city=DFW
+```
+
+## Watching a rollout
+
+Any change that replaces instances — a `deploy` with a new image, or a `restart` — starts a rollout. `datumctl compute rollout` attaches to it and prints progress per placement and city as it happens:
+
+```bash
+datumctl compute rollout api
+```
+
+Each row moves through phases — `Pending`, `Updating`, `Done` — until every placement finishes. If a placement stalls for more than 30 seconds without progress, its phase becomes `Blocked` and the command prints the reason (a quota limit, a scheduling issue) reported by the platform.
+
+
+ Ctrl-C detaches from the watch; it never cancels the rollout. Re-run `datumctl compute rollout api` at any time to reattach and see current progress.
+
+
+## Inspecting instances
+
+`datumctl compute instances` lists every instance in the project — one row per running (or attempting-to-run) copy of a workload's container in a specific city:
+
+```bash
+# Every instance in the project
+datumctl compute instances
+
+# Just one workload
+datumctl compute instances --workload=api
+
+# Just one city
+datumctl compute instances --city=DFW
+```
+
+Status reflects availability, not just whether a process happens to be running at this instant — an instance blocked on quota shows `Pending (quota exceeded)` rather than a generic "not ready." Add `-o wide` for the underlying instance type alongside the default columns, or `-o json`/`-o yaml` for the full resource.
+
+For everything about a single instance — runtime configuration, environment, network addresses, and a plain-English explanation of any failure — use `describe`:
+
+```bash
+datumctl compute instances describe api-dfw-0
+```
+
+When an instance can't start because of quota, `describe` also prints the exact next commands to run — typically checking `datumctl compute quota`.
+
+## Next steps
+
+- `datumctl compute restart --help`, `rollout --help`, and `instances --help` for the full flag reference.
+- [Deploying workloads](/datumctl/compute/deploying-workloads) — the `deploy` and `workloads` commands that create what you're operating on here.
+- [Destroying workloads](/datumctl/compute/destroying-workloads) — remove a workload and every instance it created.
diff --git a/datumctl/overview.mdx b/datumctl/overview.mdx
index 2ed52d5..4061fde 100644
--- a/datumctl/overview.mdx
+++ b/datumctl/overview.mdx
@@ -24,6 +24,9 @@ This section teaches you how to use `datumctl`; run `datumctl --help` (or `datum
Control which organization and project your commands act on.
+
+ Deploy and manage containerized workloads with the compute plugin.
+
Investigate who changed what, review events, and follow the activity feed.
diff --git a/datumctl/plugins/using-plugins.mdx b/datumctl/plugins/using-plugins.mdx
index 813f493..5a6347d 100644
--- a/datumctl/plugins/using-plugins.mdx
+++ b/datumctl/plugins/using-plugins.mdx
@@ -18,6 +18,8 @@ When you install the `compute` plugin from the official **datum** catalog, its c
datumctl compute --help
```
+(See [Compute](/datumctl/compute/overview) for what that plugin does.)
+
datumctl injects your current organization, project, and a fresh short-lived access token into the plugin automatically, so plugins work with your [active context](/datumctl/contexts-and-scoping) and [credentials](/datumctl/auth/managing-accounts) without a separate login.
Plugins come from **catalogs** (also called indexes). The official **datum** catalog is curated by Datum and always available with no setup — its plugins carry an `official` trust badge. You can also add third-party catalogs, whose plugins carry a `third-party` badge. See [Adding catalogs](/datumctl/plugins/adding-catalogs) to register more.
diff --git a/docs.json b/docs.json
index b72114d..5b0f090 100644
--- a/docs.json
+++ b/docs.json
@@ -180,6 +180,16 @@
"datumctl/resources/safe-changes"
]
},
+ {
+ "group": "Compute",
+ "pages": [
+ "datumctl/compute/overview",
+ "datumctl/compute/building-images",
+ "datumctl/compute/deploying-workloads",
+ "datumctl/compute/scaling-and-operations",
+ "datumctl/compute/destroying-workloads"
+ ]
+ },
{
"group": "Plugins",
"pages": [