How Cloudgate fits together

Cloudgate keeps everything in one tree: an Organization holds Projects, a Project holds Environments, and an Environment holds Services. Services run on Servers or in a Cloud account, both of which belong to the Organization. A Deployment is one attempt to build or run something, a Plan is what applying the Project’s configuration would change, and an Agent is a member that is an AI tool rather than a person.

The model at a glance

The diagram uses the example Organization from these docs: Northwind Labs, with a storefront Project in two Environments.

Organization Northwind Labs: members, Agents, Servers, Cloud accounts, settings

Project storefront: Project variables, Project config

Environment production, Deploy target fra-1

web pg-main

Environment staging, Deploy target nyc-edge

web pg-main

Where Services run, shared by every Project

Servers fra-1 and nyc-edge, over SSH

A Cloud account: an AWS account or a Google Cloud project

The same tree as a list, for reading aloud or copying:

• Organization: Northwind Labs
  • Members and Agents, with roles and grants
  • Servers (fra-1, nyc-edge) and Cloud accounts
  • Project: storefront, with its Project variables and Project config
    • Environment: production, deploying to fra-1
      • Services: web (an Application), pg-main (a PostgreSQL database)
    • Environment: staging, deploying to nyc-edge
      • Services: web, pg-main

Organization

The Organization is the boundary around everything else. Every Project, Server, Cloud account, member and setting belongs to exactly one Organization, and people act inside it with a role: owner, admin or member. On the Hosted instance the Organization is also what has a plan. See Organizations and Members and roles.

Project

A Project groups the Services that ship together, such as a shop’s website, API and database. It holds only Environments, plus its own variables that any Service beneath it can reference by name. Its Project config (a cloudgate.yaml, kept in Cloudgate or in your repository) can describe every Service it runs. See Projects and Environments.

Environment

An Environment is a named slice of a Project, such as production or staging. It owns the Services and has its own variables. Its Deploy target says where new Services are created: a Server, or a Cloud account and a region. Two Environments of the same Project can run in different places.

Service

A Service is one thing that runs. There are three kinds:

• An Application, built from a git repository, a Docker image or uploaded files. Its kind can be web, worker, web-private, cron, static, or an AI model.
• A Database: PostgreSQL, MySQL, MariaDB, MongoDB, Redis or libSQL.
• A Compose stack, from a Docker Compose file.

A Bucket for files is a Service too. Services talk to each other through Wired variables, which fill in one Service’s variable from another’s Output (such as a database’s url) at each deploy. See Applications, Databases and Environment variables.

Server or Cloud account

Every Service runs in one place, fixed when it is made:

• A Server is a machine Cloudgate reaches over SSH. Its setup run installs Docker, a Swarm of one and Traefik, which routes Domains and gets certificates. See Servers.
• A Cloud account is your AWS account or Google Cloud project. Cloudgate creates the cloud’s own services there (such as ECS, RDS, Cloud Run or Cloud SQL) with OpenTofu. See Cloud accounts.

On a self-hosted instance, the machine Cloudgate itself runs on, the platform host, can also be a deploy target.

Deployment

A Deployment is one attempt at one thing, with its own log, status and timings: a build and release of an Application, a backup run, a cron run, or a run that creates cloud resources. A Deployment is pending while it waits, then running, and ends done, error or cancelled. See Deployments and rollbacks.

Plan

A Plan is one Environment’s list of what applying the Project config would create, change and destroy. A push to the config’s branch, or Check for changes, makes one; nothing changes until someone presses Apply. See Project config and Plans.

Agent

An Agent is a member of the Organization that is not a person: an AI tool connected over MCP. It has its own role (Reader, Operator or Caller), its own grant to the Projects, Environments and Services it may reach, and its own keys. It can deploy and read logs, but it never applies a Plan. See Agents and the AI agents overview.

What the model does not do

Every term on this page, and the words Cloudgate avoids, are in the glossary.

Questions

Does a Service inherit its Project's variables?

No. A Service gets only its own variables. It reaches a Project or Environment value by naming it, as ${{project.KEY}} or ${{environment.KEY}}, and a reference to a name that is not set fails the deploy.

Can a Service move to another Server?

No. A Service's place, a Server or a Cloud account, is fixed when it is created. Changing an Environment's Deploy target changes only where new Services go.

Is a Server part of a Project?

No. Servers and Cloud accounts belong to the Organization, so every Project can deploy to them. An Environment names one as its Deploy target.