Docs menu

Deploy and run

Domains and networking

Give your app a nicer address or your own domain, connect services privately, and reach your project from your own machine.

Explain it

Every app gets a secure web address the moment it's live. You can add your own domain (or buy one right in CLI), let your apps talk to each other privately, and share a project on your laptop with a temporary public link.

How to do it: open an app and go to Domains. Type your domain and CLI shows the one record to add where you bought it, then sets up HTTPS by itself. No domain yet? Search for one and buy it there.

"Connect shop.example.com to my web app."

Apps in the same project reach each other by name, without going over the internet.

Every app on CLI gets a public https address the moment it's live. You can swap in a hosted subdomain or your own domain, let services talk to each other privately, and open temporary connections between your laptop and your project.

Your default address

Each app is live at https://<service>-<id>.<app domain> as soon as its first deploy is healthy. The certificate is handled for you. Find it on the service's card, at the top of the service page, or with cli status.

A hosted subdomain

For a nicer address with no DNS work, generate a hosted subdomain such as shop.<app domain>. It's live at once. Each service can have one, and you can rename it later.

In the dashboard: open the service's Settings, find Domains and press Generate domain. You can rename it there too.

From your terminal:

Terminal
cli domains generate shop

Leave out the name to get a random one, like swift-otter-4821.

Ask your agent:

"Give web a hosted address called shop."

With the API:

API
POST /v1/services/:id/domains/generate
PATCH /v1/domains/:id
JSON
{ "subdomain": "shop" }

Your own domain

Adding your own domain takes two DNS records: a TXT record that proves you own it, and a CNAME that sends traffic to CLI.

  1. Add the domain to the service.
  2. Add both records at your DNS provider. Nobody else can do this step for you, including your agent.
  3. Ask CLI to verify. DNS changes can take a few minutes to show up.
  4. Once the domain is active, https://app.example.com serves your app. The certificate is issued on the first request.

In the dashboard: press Add your domain on the app's card, or Use your own domain under the service's Settings, Domains. Type the domain and CLI:

  • works out who runs its DNS from its name servers (Cloudflare, GoDaddy, Namecheap, Porkbun, Route 53, Squarespace and others), and says where to click there;
  • shows the two records with what to type in each field for that provider (www, @, _cli-challenge.www), with copy buttons;
  • warns when a root domain (example.com) can't point at CLI at that provider, and suggests www with the root forwarding to it;
  • for Cloudflare, reminds you to set the records to DNS only (grey cloud) so CLI can see them and issue the certificate;
  • checks every 20 seconds while the steps are open, and says when the domain works.

From your terminal:

Terminal
cli domains add app.example.com
cli domains verify dom_abc123
cli domains
cli domains rm dom_abc123

Ask your agent:

"Put web on app.example.com and tell me which DNS records to add."

With the API:

API
POST /v1/services/:id/domains
GET /v1/domains/:id/help
POST /v1/domains/:id/verify

GET /v1/domains/:id/help returns the DNS provider (provider.id, name, where, tips, docs), the name servers, and each record with host, the Name field to type at that provider. suggestWww is set when it's a root domain at a provider without ALIAS records.

JSON
{ "hostname": "app.example.com" }

If verification fails, you get DOMAIN_NOT_VERIFIED with a list of what's missing or wrong. Fix the records and try again, no faster than every 2 minutes. DOMAIN_TAKEN means another project already uses that hostname.

Buy a domain

You can buy a domain without leaving CLI, and it's pointed at your app for you: no DNS records to copy.

  1. On the service, open Domains and use Buy a domain. Type a name (acme) to check the popular endings, or a full domain (acme.dev).
  2. Each result shows the price for the first year and what it renews for, in USDC.
  3. Choose Buy, agree to the registration terms, and confirm. The price comes out of the project's credit.

CLI registers the domain, points the root and www at the service, adds both to it, and the certificate follows within a few minutes. Owners and admins can buy; an agent's key with a spending limit can't go past it.

API
GET  /v1/domains/search?q=acme
POST /v1/services/:id/domains/buy {"domain": "acme.dev", "agreeToTerms": true}

Renewals come out of credit a month before the domain expires. Turn Auto-renew off in project settings (Domains you own) to let it lapse. If there isn't enough credit, the domain shows as expiring so you can top up.

More DNS records (for email, verification and so on) can be added to a domain bought here: POST /v1/purchased-domains/:id/records {"type": "MX", "name": "", "content": "…", "prio": 10}. Setting up email for apps on it writes its records automatically (/docs/email).

If the registrar can't register the domain, the price goes straight back to the project.

Private networking

Every service can reach every other service in the same environment at <name>.internal. Traffic on this network never leaves your project, and other projects can't see it. Databases live only on the private network unless you open a port.

For example, if your web app calls an api service on port 8080:

JSON
{ "vars": { "API_URL": "${{api.PRIVATE_URL}}" } }

${{api.PRIVATE_URL}} resolves to http://api.internal:8080. Using the reference instead of typing the address means it follows the service's port. Each environment has its own network, so the same reference in staging points at staging's api. See Variables and configuration.

Open a database to your machine

Sometimes you need to reach a database from your laptop, for a GUI client or a one-off script. You can open a public port that only accepts TLS connections, only from the address you choose, and closes itself after a set time.

In the dashboard: the database's Connect tab has a button to open and close a public port, and shows the public URL.

From your terminal:

Terminal
cli db connect postgres --public

This opens a port for your machine's address and prints the URL.

With the API:

API
PATCH /v1/services/:dbId
JSON
{ "publicTcp": { "hours": 2, "allowFrom": "me" } }

allowFrom is "me" (the address the request came from), one IP address, or a CIDR range. hours can be 1 to 168. Connect with sslmode=require.

Tunnels: share a local port

A tunnel gives a port on your machine a public https address, so you can show someone what you're working on or receive webhooks while developing.

From your terminal:

Terminal
cli tunnel 3000
cli tunnel 3000 --name demo

The address stays up while the command runs.

With the API: POST /v1/projects/:id/tunnels returns a token, then connect to wss://…/v1/tunnels/connect?token=….

Run locally with your project's settings

cli run runs a local command with the service's variables, so your laptop uses the same configuration as CLI:

Terminal
cli run npm test

cli dev goes one step further: it also opens the project's databases to your machine only, for 4 hours, and swaps their private URLs for ones that work from your laptop:

Terminal
cli dev npm run dev
cli dev --tunnel 3000 npm run dev
cli dev --no-db npm run dev

With --tunnel, your local server also gets a public https address, passed to it as PUBLIC_URL. With --no-db, databases stay closed.

Next steps