Apps
An app is a running container: an image, some CPU and memory, one or more ports, and optionally command arguments, environment variables, mounted volumes, and labels. Every app gets an auto-assigned public URL, so the moment it’s healthy you can reach it from the internet.
This page explains the app model. For the step-by-step workflow, see Deploying your app. For the exact HTTP endpoints, see the Apps API reference.
From the dashboard
Section titled “From the dashboard”Deploy an app in three steps — no Docker knowledge required.

Click Deploy App and pick a name and container image:

Choose a size and how many instances to run:

g3.small up to g7.2xlarge) and instance count. Sizes map to CPU and memory — see Resource tiers.Add command arguments, environment variables, volumes, labels, registry credentials, a “sleep when idle” toggle, and a run-once toggle (all optional):

What an app is made of
Section titled “What an app is made of”| Field | Meaning | Example |
|---|---|---|
name |
App name — lowercase letters, numbers, and hyphens | my-api |
image |
Container image to run | docker.io/nginx:latest |
instances |
How many copies (replicas) to run | 1 |
ports |
Ports exposed by the container | [{ name: "web", number: 80 }] |
args |
Command arguments passed to the container (space-separated) | ["--production"] |
env |
Environment variables injected at runtime | DATABASE_URL, NODE_ENV |
mounts |
Volumes mounted into the container | [{ volume_id, path: "/data" }] |
tags |
Labels — free-form key: value metadata |
{ team: "core" } |
cpu / memory |
Resource allocation (millicores / MB) | 256 / 512 |
hibernated |
Sleep the app and release resources | false |
ephemeral |
Run once — discard the container filesystem on restart | false |
pull_secret_id |
Optional private-registry credential | "" |
version |
Arbitrary version label | "1.0.0" |
Creating an app
Section titled “Creating an app”With the REST API:
{ "project_id": "…", "name": "my-api", "image": "docker.io/nginx:latest", "ports": [{ "name": "web", "number": 80 }], "args": ["--production"], "env": [{ "name": "NODE_ENV", "value": "production" }], "tags": { "team": "core" }, "cpu": 256, "memory": 512, "instances": 1, "hibernated": false, "ephemeral": false}curl -X POST https://api.cumin.dev/apps \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "project_id": "…", "name": "my-api", "image": "docker.io/nginx:latest", "ports": [{ "name": "web", "number": 80 }], "cpu": 256, "memory": 512, "instances": 1, "hibernated": false }'Ports and URLs
Section titled “Ports and URLs”Each port can expose a public hostname. Ghaymah auto-assigns a URL in the form
https://{name}-{port}-{hash}.hosted.ghaymah.systems (or a .hosted.cumin.dev equivalent),
so you don’t need to configure DNS to get started. Attach a custom domain
when you’re ready for production.
Private networking
Section titled “Private networking”In addition to its public URL, every app gets an internal hostname that’s only reachable from inside your project — no public IP and no internet exposure. Other apps and services in the same project can reach it directly, which is how you wire up a Redis cache, an internal API, or a database without exposing it publicly.
The internal hostname looks like my-site-9f2c4b92 and is addressable on the app’s port:
http://my-site-9f2c4b92:80Set an app to internal only to drop its public URL entirely — the public URL above is separate and optional. Internal-only apps still receive an internal hostname so other services can reach them, but nothing from the internet can.
Health checks
Section titled “Health checks”You can attach a health check to any port so the platform knows when your app is ready:
{ "ports": [ { "name": "web", "number": 80, "health": { "path": "/healthz", "interval": 10, "timeout": 5 } } ]}The app reports a status (running, error, failed, …) that reflects its health and
readiness.
Hibernation
Section titled “Hibernation”Set hibernated: true to put an app to sleep and release its resources while keeping its
configuration. Wake it by setting hibernated: false — a cheap way to pause side projects
you’re not actively using.
Command arguments
Section titled “Command arguments”Pass extra arguments to the container’s command — the equivalent of appending flags after the
image in docker run. In the dashboard they’re space-separated; in the API they’re an array:
{ "args": ["--production", "--log-level=info"] }Labels
Section titled “Labels”Labels are free-form key: value metadata attached to the app. Use them to track teams, cost
centers, or environments without polluting your application code:
{ "tags": { "team": "core", "env": "production" } }Run once
Section titled “Run once”Enable run once (the ephemeral flag) to discard the container’s filesystem when it stops,
so every run starts from a clean image. It’s meant for one-off jobs and batch tasks that don’t
need to keep state between runs — anything that must persist still belongs on a
volume.
Volumes and environment
Section titled “Volumes and environment”- Mount a volume to persist files across restarts — see Volumes.
- Inject secrets as environment variables or use the secrets API — see Secrets.
- Connect to a database by pointing
DATABASE_URLat a managed PostgreSQL instance.
Lifecycle at a glance
Section titled “Lifecycle at a glance”create ──▶ provisioning ──▶ running ──▶ (scale / update / hibernate) ──▶ delete │ └── error / failed (read the logs to debug)Stream logs any time from the dashboard, or via the API: GET /logs/{app_id}?max=100.
Next steps
Section titled “Next steps”- Deploying your app — the full deploy workflow
- Apps API reference — every endpoint and field
- Volumes — attach persistent storage