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

# Containers

> Deploy and operate long-lived tenant services in Verglas Cloud.

Containers run service images in Verglas Cloud. Use a container when the workload needs a server process, a web UI, an MCP endpoint, or durable mounted storage. Use a worker for bounded scheduled or event-driven runs.

<Note>
  The current CLI manages containers through the cloud control plane. Local container execution is outside the current CLI contract.
</Note>

## Deploy a catalog app

List the curated applications available to your tenant:

```bash theme={null}
verglas containers catalog
```

Deploy one by catalog ID:

```bash theme={null}
verglas containers deploy <catalog-id>
```

The command is idempotent. If the app already exists, Verglas reports the existing deployment.

Inspect and configure the deployed container:

```bash theme={null}
verglas containers list
verglas containers get <container-id>
verglas containers config <container-id>
```

Set a normal value on the command line and read a secret from standard input:

```bash theme={null}
printf '%s\n' "$APP_API_KEY" | \
  verglas containers config <container-id> \
    --mode custom \
    --set REGION=us-west-2 \
    --set API_KEY=-
```

The read path reports whether a secret is set. It never returns the secret value.

## Push your own image

Push the image to a registry that Verglas Cloud can reach, then register it in the tenant registry:

```bash theme={null}
docker build -t ghcr.io/acme/orders-api:1.2.0 .
docker push ghcr.io/acme/orders-api:1.2.0

verglas containers push docker://ghcr.io/acme/orders-api:1.2.0 \
  --name orders-api \
  --tag 1.2.0
```

`containers push` registers the image for cloud conversion and launch. It does not upload a purely local Docker image.

## Create from a specification

Save the complete control-plane request as JSON or TOML. The current CLI passes the specification through as the container request body.

```json container.json theme={null}
{
  "name": "orders-api",
  "image": "orders-api:1.2.0",
  "mode": "stateless",
  "min_instances": 0,
  "max_instances": 4,
  "desired_instances": 0,
  "vcpus": 1,
  "mem_mib": 1024,
  "edge_sockets": false
}
```

Create and inspect the deployment:

```bash theme={null}
verglas containers create --file ./container.json
verglas containers list
```

## Scale and stop

```bash theme={null}
verglas containers scale <container-id> --instances 3
verglas containers stop <container-id>
verglas containers resume <container-id>
```

Stopping a container scales it to zero. Resuming restores the deployment through the control plane.

## Attach durable storage

Create a cloud block volume before referencing it in a container specification:

```bash theme={null}
verglas volumes create orders-data --size 20GiB
verglas volumes get orders-data
```

Volumes grow but do not shrink:

```bash theme={null}
verglas volumes resize orders-data --size 50GiB
```

Verglas refuses to delete an attached volume.