Get started

Core concepts

Codara organizes everything into five nested levels. Once the hierarchy clicks, the rest of the product follows from it.

The hierarchy

Organization              Acme Inc.└── Workspace             Customer apps    └── Project           website        └── Environment   production            ├── Service   web            ├── Service   api            ├── Database  main-db            └── Job       nightly-report

Everything inside one environment is co-located and can talk to itself privately. Everything outside it is isolated.

A note on naming

The product calls the customer boundary a workspace and a running application a service. The current API and CLI retain the legacy terms client and app for compatibility. Command examples use those exact API names.

Organization

The account boundary for people, invitations, roles, billing and ownership. Every person signs in with an individual identity and joins an organization through an invitation.

Workspace

A boundary inside an organization that owns projects, contact details, spend controls and cost history. A workspace can represent a customer, a company department or internal products. Internal is a workspace, not a customer.

Workspaces are represented as clients by the current API and CLI. The slug is globally unique and becomes part of default service URLs, so it can be visible to end users.

Project

A grouping of related services inside a workspace. Creating a customer account creates one empty default workspace. Projects are independent: create one directly in that default workspace, or add an optional empty workspace when you need a separate organizational boundary.

One project per product — and usually one repository

A project is the unit of a real piece of work, not a folder to park things in. The working rule is one project per product, normally backed by its own GitHub repository. A workspace’s marketing site, its CRM and its internal API are three projects, not three services inside one.

When you are about to add a service, the default answer is create a new project for it. Only add to an existing one when the new service genuinely belongs to that same product — a worker for its queue, say, or its scheduled jobs.

Codara enforces this rather than guessing. If a workspace owns more than one project and you do not say which to use, the request is refused and lists the candidates instead of picking one. Nothing lands in a project by accident.

Project slugs are up to 32 characters and unique within their workspace. The names default and internal are reserved. A project can only be deleted once it holds no apps and no databases.

Environment

A deployment target inside a project — production, staging, and so on. Every project starts with a production environment.

Environments are the isolation boundary. Two environments of the same project have separate apps, separate databases and separate environment variables. Promoting a release from one to another is a first-class operation that reuses the exact image rather than rebuilding — see Environments.

Environments come in two kinds: persistent ones you create yourself, and preview ones that can be created automatically per pull request when a project opts in.

App

A running service: one container image, its replicas, its port, its environment variables and its domains. An app belongs to exactly one environment.

The same logical service usually exists once per environment — a web app in production and another in staging. Codara groups those under a shared service, which is what environment-wide shared variables attach to.

App names are up to 63 characters, lowercase, hyphen-separated, and unique within their environment.

Deploy

One build-and-release attempt for one app. Deploys are append-only: rolling back or promoting creates a new deploy that points at an older image rather than rewriting history, so the timeline always reflects what actually happened.

Status	Meaning
queued	Waiting for a build slot.
cloning	Fetching your repository at the target commit.
building	Producing the container image.
pushing	Uploading the image to the registry.
deploying	Image built; the new version is rolling out.
running	Live and serving traffic.
failed	The build or the rollout failed. The previous release keeps serving.
cancelled	Stopped before it was promoted.
skipped	A push that matched no watch path.

Built is not the same as live

A successful build only means the image exists. The release becomes running only once the new pods are genuinely rolled out and healthy. A rollout that never becomes healthy is marked failed and your previous version continues to serve traffic untouched.

Other resources

Database

A managed Postgres, MySQL, MariaDB, MongoDB or Redis instance living in an environment. Connecting one to an app injects its credentials as environment variables. See Databases.

Volume

Persistent disk attached to an app at a mount path, for state that must survive restarts. An app with a volume runs as a single replica. See Storage.

Bucket

S3-compatible object storage for user uploads and other blobs. No self-serve plan includes buckets; they are available by separate agreement. See Storage.

Job

A task that runs to completion rather than serving traffic — either one-shot or on a cron schedule. See Jobs and cron.

Naming rules

Resource	Length	Rules
Workspace slug	2–63	Globally unique. Lowercase letters, digits and hyphens. Becomes a DNS name.
Project slug	1–32	Unique per workspace. `default` and `internal` are reserved.
Environment slug	1–32	Unique per project. `default` is reserved.
App name	1–63	Unique per environment.

The combined length is capped at 63 characters

Workspace, project and environment slugs are joined together internally, and the result cannot exceed 63 characters. Each individual maximum is generous enough that all three at full length will overshoot. If you hit this, the error names which slug to shorten — but it is far easier to keep slugs short from the start.

How things are addressed

Most CLI commands and API calls need to know which workspace, project and environment you mean. When you leave them out, Codara falls back to your default workspace and the production environment. The compatibility flag is still named --client.

bash

# Explicit$ codaracloud apps list --client my-workspace # Scope flags where a command supports them$ codaracloud apps update web --client my-workspace --project website --env staging --port 3000

Scope flags are not available everywhere

Several command groups — env, domains, logs, metrics and apps get — take no scope flags at all and always resolve against your default workspace and the production environment. If you run the same app name in more than one environment, use the console or pass scope where the command supports it. There is also no way to persist a “current” workspace or environment between invocations.

Private networking

Apps in the same environment can reach each other over the internal network without going through the public internet. Each app is given its private address as an environment variable:

CODARA_PRIVATE_URL — the full internal URL.
CODARA_PRIVATE_DOMAIN — the internal hostname.

Traffic across environments, projects or workspaces is blocked by default.

Private traffic does not wake a sleeping app

Internal requests bypass the layer that wakes sleeping apps on demand. If one app depends on another privately, the dependency must not have autosleep enabled or the call will fail.

Last updated 25 September 2026