> ## Documentation Index
> Fetch the complete documentation index at: https://datum.net/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Compute commands

> Deploy and manage containerized workloads on Datum Cloud with the datumctl compute plugin.

> [!NOTE]
>
> Compute is in preview, and each project needs approved access before it can deploy. For product guides, see [Compute](https://datum.net/docs/compute/overview.md). To deploy your first app, see [Deploy an app](https://datum.net/docs/getting-started/first-workload.md).

`datumctl compute` deploys a container image as a *workload* that runs in one or more Datum Cloud locations, and provides the day-to-day commands to scale, restart, and delete it. It's a first-party plugin instead of a built-in command. After you install it, its commands behave like the rest of the CLI.

```bash theme={null}
datumctl plugin install compute
datumctl compute --help
```

> [!NOTE]
>
> New to plugins? [Using plugins](https://datum.net/docs/datumctl/plugins/using-plugins.md) covers installation, upgrades, and how a plugin inherits your active context and credentials. Not installed `datumctl` itself yet? Start with [Install](https://datum.net/docs/datumctl/install.md).

## 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](https://datum.net/docs/compute/placement-and-scaling.md). |
| **Placement** | A named group of locations and a scale policy (minimum replica count) in a workload. A flag-based `deploy` creates a single placement named `default`. |
| **Location** | A Datum Cloud region a workload can run in, for example `us-central-1`. The `--city` flag selects every location in a city by its code, such as `DFW`. |
| **Instance** | One running copy of a workload's container in one location. A placement with `--min=2` across two locations produces four Instances. |

`compute` is project-scoped: every command reads `--project` (or your active context's project, injected automatically — see [Contexts & scoping](https://datum.net/docs/datumctl/contexts-and-scoping.md)). 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:

> **Not requested**
>
> No request has been made yet. On an interactive terminal, the gate offers to submit one for you.

> **Pending approval**
>
> A request is awaiting a manual decision by the service provider. Latency is unbounded.

> **Active**
>
> The project is entitled — every `compute` command runs normally.

> **Denied / Revoked**
>
> 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 theme={null}
datumctl compute deploy api --image=ghcr.io/acme/api:1.4.2 --location=us-central-1 --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 theme={null}
# 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 theme={null}
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 theme={null}
datumctl compute quota
```

```text theme={null}
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 theme={null}
datumctl compute quota --constrained
```

## Find your way around

> **[Building images](https://datum.net/docs/datumctl/compute/building-images.md)**
>
> Turn a Dockerfile into an image Compute can run, and check compatibility before you deploy.

> **[Deploying workloads](https://datum.net/docs/datumctl/compute/deploying-workloads.md)**
>
> Deploy a workload from flags or a manifest, and read back its health across locations.

> **[Operations](https://datum.net/docs/datumctl/compute/scaling-and-operations.md)**
>
> Roll restarts, watch a rollout, and debug individual Instances.

> **[Viewing logs](https://datum.net/docs/datumctl/compute/viewing-logs.md)**
>
> Read Instance output or ALB access logs from the terminal.

> **[Destroying workloads](https://datum.net/docs/datumctl/compute/destroying-workloads.md)**
>
> Tear down a workload and every Instance it created.

## Related

* `datumctl compute --help` and `datumctl compute <command> --help` for the full flag reference.
* [Compute](https://datum.net/docs/compute/overview.md) — product guides for runtime classes, configuration, placement, and publishing workloads.
* [Open a shell with datumctl](https://datum.net/docs/compute/instance-shell.md#datumctl) — `datumctl compute exec` opens an interactive shell or runs a single command in a running Instance.
* [Using plugins](https://datum.net/docs/datumctl/plugins/using-plugins.md) — how the `compute` plugin is installed, upgraded, and trusted.
* [Contexts & scoping](https://datum.net/docs/datumctl/contexts-and-scoping.md) — how the project a `compute` command runs against is resolved.
* [Output formats & scripting](https://datum.net/docs/datumctl/output-and-scripting.md) — `-o json`/`-o yaml` patterns that apply across `compute` subcommands.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.