Deploy and run
Run in your own cloud
Run a project's services on machines in your own AWS, Google Cloud or other account, while CLI keeps deploying, scaling, logging and billing them.
You can run a project's apps on your own servers (in your AWS, Google Cloud or any machine) while CLI still handles deploys, scaling, logs, backups and billing. This is often called "bring your own cloud".
How to do it: in project settings, open Servers and regions, add a server, and run the one install command CLI shows on your machine. Then choose which apps run there.
Compute on your own machines costs a fraction of the usual rate, since you pay your cloud for it.
You can run a project's services on machines in your own cloud account instead of CLI's. CLI still does the deploying, scaling, logs, backups and billing; the containers just run on your machines. This is often called "bring your own cloud" (BYOC).
This page covers why you'd do it, how the connection works, adding a machine from the dashboard or the API, each install format, keeping a project on its own servers, what it costs, and how to rotate, check and remove a server.
Why run in your own cloud
- Data residency. Your services and databases stay on machines in the account and region you choose. A project rule can make sure nothing starts anywhere else.
- Your own cloud spend. You pay your cloud provider for the machine directly, so credits or commitments you already have with them apply. CLI charges a management fee instead of its compute price (see Billing below).
- Compliance. Some customers and auditors need to know exactly where workloads run. With your own servers, the machines, their disks and their network are yours to control and to show.
How the connection works
Each machine runs CLI's worker: the only process that talks to Docker. Normally CLI calls a worker at an address. A worker in your cloud works the other way round: it connects out.
- The worker opens a WebSocket to
wss://<CLI API>/v1/workers/connectand keeps it open. - To connect, it shows a token: an HMAC of its server id and the current time, made with the server's secret. CLI refuses the connection if the token doesn't match or the machine's clock is more than 5 minutes off.
- CLI sends the worker's usual requests down that connection. Every request is still signed with the worker secret and checked by the worker, exactly as before; the socket only carries them. The worker only answers its own paths.
- If the connection drops, the worker reconnects on its own, waiting 1 second and then twice as long each time, up to 30 seconds.
The worker listens only on 127.0.0.1, so nothing outside the machine can reach it.
What needs to be open
| Direction | What | Why |
|---|---|---|
| Inbound | 80 and 443 | Web traffic to your apps, and certificates from Let's Encrypt |
| Inbound | Nothing else | CLI never connects in: the worker connects out |
| Outbound | HTTPS to the CLI API | The worker's connection |
If your apps don't serve the public, you can put a load balancer in front instead of opening 80 and 443 on the machine itself.
Add a server from the dashboard
You need to be an admin of the project.
- Open the project's Settings and find Servers and regions.
- Choose In your cloud: it connects out.
- Enter a name, a region label (for example
fra) and the app domain your apps will live under (for exampleapps.example.com). - Click Add server.
- CLI shows the install files in four tabs: Cloud-init, Terraform: AWS, Terraform: Google Cloud and Docker. Copy or download the one that suits you.
- Start the machine with it, and point
*.apps.example.comat the machine.
The server shows as online within a minute of the worker starting.
The other choice, CLI calls it at an address, is for a machine CLI can reach over https at a URL you give, with the worker's port open.
Add a server with the API
POST /v1/projects/:id/servers
{"name": "eu-own", "region": "fra", "appDomain": "apps.example.com", "connect": true}With connect: true, leave out url. You can add "gpus": {"L4": 2} for a machine with GPUs, which needs the NVIDIA container toolkit.
The answer is the new server (its id is srv_…, its mode is connect and its status starts as pending), plus:
| Field | What it is |
|---|---|
secret | The worker secret, shown only now |
install.env | The worker's .env file |
install.cloudInit | Cloud-init user data for a fresh Ubuntu machine |
install.terraform.aws, install.terraform.gcp | Terraform for one machine on AWS or Google Cloud |
install.docker | One docker run command |
install.compose | The docker-compose.yml for the machine |
install.steps | The steps, in words |
The worker's settings in install.env include:
CLI_WORKER_SERVER_ID=srv_…
CLI_WORKER_SECRET=…
CLI_WORKER_CONNECT_URL=wss://<CLI API>/v1/workers/connect
CLI_WORKER_HOST=127.0.0.1
CLI_APP_DOMAIN=apps.example.comInstall formats
Every format ends with the same thing running: CLI's worker, connecting out, and Traefik serving your apps on 80 and 443. The machine should run Ubuntu 22.04 or 24.04.
Cloud-init
Paste it as the machine's user data when you create it, on any cloud that supports cloud-init. On first boot the machine:
- installs
curl,ca-certificatesandiptables-persistent; - writes the worker's settings to
/opt/cli/.env, readable only by root; - downloads and runs the host setup script from
/v1/byoc/host-setup.sh, which installs Docker, gVisor, BuildKit and Railpack, creates the app network and sets the firewall rules for app containers; - downloads
docker-compose.ymlfrom/v1/byoc/compose.ymland starts it.
Terraform for AWS
One EC2 instance using the cloud-init above. Save the cloud-init as cloud-init.yaml next to main.tf (the dashboard has a button for it), then:
terraform init
terraform applyIt uses the latest Ubuntu 24.04 image, a t3.large with a 100 GB encrypted disk by default (variables region, instance_type and disk_gb), requires IMDSv2, and makes a security group that lets in only 80 and 443. It prints the machine's public_ip: point your app domain's wildcard at it.
Terraform for Google Cloud
One Compute Engine VM using the same cloud-init. Save cloud-init.yaml next to main.tf, then:
terraform init
terraform apply -var project=<your project>It defaults to an e2-standard-2 in us-central1-a with a 100 GB disk and secure boot, on Ubuntu 24.04, with a firewall rule for 80 and 443 only. It prints public_ip too.
Docker
A single docker run for a machine that already has Docker and has run the host setup script. It starts the worker with host networking and the Docker socket.
Place services on your servers
By default a service runs on the project's default server unless you choose another in its settings (Runs on in the dashboard, or PATCH /v1/services/:id {"serverId": "srv_…"}). See Scaling and running.
Keep everything on your own servers
For data residency, an admin can make the whole project keep to its own servers.
In the dashboard: under Servers and regions, tick Keep everything on our own servers and pick where new services go.
With the API:
PUT /v1/projects/:id/placement
{"ownServersOnly": true, "defaultServerId": "srv_…"}GET /v1/projects/:id/placement shows the current setting. Turning it on needs at least one server of your own, and a default server that belongs to the project.
Once it's on:
- New services go to the default server.
- Anything that would start on CLI's machines is refused with
PLACEMENT_REQUIRED(409). The error'sdetails.fixholds the request that moves the service, for examplePATCH /v1/services/svc_… {"serverId": "srv_…"}. - Sandboxes are refused with
PLACEMENT_REQUIRED, because they always run on CLI's machines (see /docs/sandboxes). - The rule covers the project's environments too.
Turning the rule on doesn't move services that are already running elsewhere. The check runs before anything starts, so the next deploy of such a service is refused until you move it. Moving an app rebuilds it on the new server.
Billing
Compute on your own server isn't charged at CLI's rates, since you pay your cloud for the machine. CLI charges a management fee instead: by default 15% of the usual compute price for the same CPU and memory. The operator of a CLI server sets this with CLI_BYOC_FEE_BPS (see /docs/self-hosting).
The fee applies both to the check that your balance covers an hour before something starts, and to the per-minute metering after. See Credit, pricing and billing.
The hold for services running flat out on CPU for a long time doesn't apply on your own servers: your machine is yours to run hot.
Rotate the secret
If the install files leak, or someone who had them leaves, make a new secret. The old one stops working at once. In the dashboard, press New secret beside the server in Servers and regions; the new install files show once, as when you added it. With the API:
POST /v1/servers/:id/rotate-secretThe answer holds the new secret and fresh install files. Restart the worker with the new CLI_WORKER_SECRET; until you do, it can't take requests.
Check a server
The Servers and regions list shows each server's status (online, offline or pending) and when it last answered. Check asks the worker now.
With the API:
GET /v1/projects/:id/servers
POST /v1/servers/:id/checkEach server has status, mode (connect for a worker in your cloud), workerVersion and lastSeen. A connected worker shows as online as soon as its connection opens, and offline when it closes.
Remove a server
Move the services on it elsewhere first; otherwise CLI answers CONFLICT. Then click Remove, or:
DELETE /v1/servers/:idRemoving it in CLI doesn't touch the machine. Shut it down in your cloud yourself.
Limits and honest notes
- Several control-plane replicas. A worker connects to one replica. Requests that arrive at another replica are passed to it in one piece, so a live log stream opened through another replica arrives when the stream ends rather than line by line. Through the replica holding the connection, it streams as usual.
- Keep the setup in place. The machine must keep Docker and the firewall rules from the host setup script. They're what keeps app containers away from each other, from the cloud's metadata endpoint and from private ranges.
- Clock. The worker's clock must be within 5 minutes of CLI's, or it can't connect.
- Changes to who has access. Only admins check, rotate and remove servers, and change placement. Adding a server takes a signed-in person: an API key can't add one, even with the admin role. A server that's the project's default for new services can't be removed while the project keeps to its own servers.
For the platform's own set-up and the host setup script, see Running CLI yourself.