Core concepts

Comwit Cloud is a project workspace that wraps two systems behind one product API and console: databases (libSQL, reachable at https://db.cloud.comwit.io) and runtime apps (Next/V8 isolate apps). This page defines the handful of terms you’ll meet everywhere else in these docs, so the rest reads smoothly.

You can drive the platform three ways — the web console at https://cloud.comwit.io, the comwit CLI, and the public platform API at https://api.cloud.comwit.io. The CLI and console both call the same platform API, so anything the CLI does, you can do with a raw HTTP call using a token.

Project

A project is the workspace that owns everything else. It groups its databases, apps, and domains, and your access is scoped per project. A project is identified by its project_id, and your token grants access to specific projects.

Note

When you log in with the CLI you can pin a default project with comwit login --project <projectId>, so you don’t have to pass --project on every command. See Install the CLI.

Database

A database is a libSQL database (powered by Louhi), reachable at https://db.cloud.comwit.io. It is identified by a database_id and has a database_url you connect to.

One-time tokens

A database access token is returned once, at create or rotate time, and is never stored by Comwit. Copy it immediately and keep it safe — if you lose it, you must rotate to get a new one. See Create and connect a database.

App

An app is a deployable runtime application (powered by brrrd), identified by an app_id. You create an app, deploy code to it, set environment variables, roll back, and attach hostnames to it. See Apps overview.

Build

A build is the artifact produced by a single deploy of an app, identified by a build_id. Each deploy produces a new build, and the active build serves traffic. Rolling back means making a previous build the active one again. See Deploy an app.

Runtime app hostname

A runtime app hostname is a hostname attached to one app. There are two flavors, which differ only in who publishes the DNS records:

• Manual DNS — Comwit returns the DNS records you need, and you publish them yourself at whatever DNS provider hosts that hostname.
• Automatic DNS — Comwit writes the records for you into a project domain’s Route 53 zone, so there’s nothing for you to publish.

See Custom hostnames.

Project domain

A project domain is a domain you already own that you’ve onboarded for delegated DNS, so Comwit can manage its Route 53 records. Onboarding a domain is what makes Automatic DNS hostnames possible, and it’s how you manage DNS records through Comwit. See Domains overview and Bring your own domain.

Token

A token is how you authenticate every request to the platform API. A user token looks like cwt_<hex> — a personal access token tied to your user. It can only do what its scopes allow, and it can only touch projects you are a member of. You send it as a bearer token:

Authorization header

Authorization: Bearer cwt_xxx

Caution

The internal PLATFORM_API_SERVER_TOKEN is an operator/web token used by the console itself. It is never a user CLI token — your token always starts with cwt_. See Authentication.

Get a token with comwit login (device flow) or by creating a personal access token in the console. Full walkthrough in Install the CLI.

Scopes

Scopes are the permissions attached to a cwt_ token. They decide which actions the token can perform; a request for an out-of-scope action (or a project you’re not a member of) returns 403.

Scope	Grants
project:read	List projects you can access
database:read	List/inspect project databases
database:write	Create databases
app:read	List/inspect apps, builds, env, domains
app:write	Create/delete apps, set env, attach hostnames
app:deploy	Deploy builds, roll back
domain:read	List/inspect project domains and DNS records
domain:write	Onboard domains, manage DNS records
domain:purchase	Registrar purchase

Planned

domain:purchase (registrar purchase) is planned, not yet live. Delegated DNS for a domain you already own is live; registrar purchase through Comwit is not.

Where to go next

• Quickstart — token → database → app, end to end.
• Authentication — how cwt_ tokens and scopes work in detail.
• Databases overview and Apps overview.