Skip to content

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.

Deploy an app in three steps — no Docker knowledge required.

Ghaymah Apps page
The Apps page lists your deployed apps.

Click Deploy App and pick a name and container image:

Deploy App form — details
Step 1 — name your app (lowercase letters, numbers, and hyphens) and pick an image from the popular list or any registry.

Choose a size and how many instances to run:

Deploy App form — resources
Step 2 — pick a size (from 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):

Deploy App form — advanced
Step 3 — optional advanced settings: command arguments, env vars, volumes, labels, registry credentials, “sleep when idle”, and “run once”.
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"

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
}
Terminal window
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 }'

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.

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:80

Set 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.

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.

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.

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 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" } }

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.

  • 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_URL at a managed PostgreSQL instance.
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.