Runtime apps overview

A runtime app is a deployable Next/V8 isolate application that Comwit Cloud runs for you. You write a Next app, deploy a build, and Comwit Cloud serves it on the internet — no servers to provision and no edge platform configuration on your side.

Behind the scenes runtime apps are powered by brrrd, Comwit Cloud’s runtime/fleet plane. You never talk to brrrd directly, though: everything you do to a runtime app — create it, deploy builds, set environment variables, roll back, attach custom hostnames, delete it — goes through the product API at https://api.cloud.comwit.io (or the comwit CLI, which calls the same API).

How a runtime app is identified

Runtime apps live inside a project, and every app has two stable identifiers you’ll use in CLI commands and API routes:

• projectId — the project the app belongs to.
• appId — the app itself, unique within its project.

Note

Internally, the public projectId maps to a brrrd tenant and the public appId maps to a brrrd service id. You don’t need to know or use those internal ids — the product API hides them, and you only ever pass projectId and appId.

The product API is intentionally product-shaped, not a thin pass-through to brrrd. For example, listing apps for a brand-new project that has never created an app returns 200 with an empty list rather than an error:

List the runtime apps in a project (CLI)

comwit apps list --project <projectId>

The equivalent API route

GET /v1/projects/{projectId}/apps        → { "apps": [] }

Detail and mutation routes for an app that doesn’t exist still return 404.

What an app looks like

When you create an app you give it a name; the API assigns the appId:

Create an app (CLI)

comwit apps create --project <projectId> --name web

Create an app (API)

POST /v1/projects/{projectId}/apps        { "name": "web" }

An app resource carries:

• app_id — the app’s appId.
• name — the human-friendly name you chose.
• active_build_id — the build currently being served (if any).
• builds — the list of builds you’ve deployed.

A runtime app starts out empty. It only serves traffic once you deploy a build and that build becomes the active build.

The lifecycle of a runtime app

Working with a runtime app follows a simple loop, and each step has its own detailed page:

1. Deploy a build. Package your built Next app and upload it; the new build becomes active. See Deploy a runtime app. Comwit Cloud keeps your build history, so you can also roll back to a previous build without re-uploading anything.
2. Configure environment. Set plain configuration values your app reads at runtime. See Environment variables.
3. Attach custom hostnames. Serve the app on your own domain instead of (or in addition to) its default address. See Custom hostnames.

Tip

New to Comwit Cloud? Start with the Quickstart to install the CLI, sign in, and deploy your first app end to end. The concepts page explains projects, apps, and databases together.

Environment values are plain, not secret

App environment variables are plain configuration only. The live platform does not store secrets for app env — attempting to mark a value as secret is rejected with a 400 error. Keep real secrets out of app environment until a secret backend is intentionally enabled, and use this for non-sensitive configuration. Full details are on the Environment variables page.

Caution

A dedicated secret backend for app environment is planned, not yet live. Until it ships, do not put credentials, API keys, or other sensitive values in app environment variables.

Custom hostnames in brief

By default your app is reachable at the address Comwit Cloud assigns it. To serve it on a domain you control, you attach a hostname. Comwit Cloud supports two DNS modes:

• Manual DNS — the API returns the DNS records to publish at your own DNS provider, then you finalize activation.
• Automatic DNS — when the hostname is the apex or a subdomain of a managed project domain, Comwit Cloud creates the required DNS records for you in that domain’s zone.

The Custom hostnames page walks through both modes. If you also manage the domain itself in Comwit Cloud, see the Domains overview and Connect a domain to an app.

Deleting an app

Deleting an app tears it down and reports what was cleaned up — the routing pointer, runtime resources, build artifacts, environment keys, and attached hostnames. If any DNS cleanup still needs to happen at your DNS provider, the response lists it for you.

Delete an app (API)

DELETE /v1/projects/{projectId}/apps/{appId}

Where to go next

• Deploy a runtime app — package, upload, and activate a build, plus rollbacks.
• Environment variables — set and remove plain config values.
• Custom hostnames — serve your app on your own domain.
• API authentication — how the comwit CLI and API authenticate.