Reference
Your first worker and a testnet payment
Step by step, bring up a worker server for a CLI control plane that runs elsewhere (Railway, for example), deploy an app on it, and take a real testnet USDC payment.
This is a walkthrough for people running their own CLI server: it connects a machine that runs apps and checks a real test payment goes through. It takes about half an hour.
Do you need this page? Only if you're setting up your own CLI platform. If you use clicloud.app, CLI's servers are already set up for you.
This walkthrough takes a control plane already running somewhere without Docker, such as Railway, and gives it a server to run apps on. At the end, apps deploy to your own machine with HTTPS, and a real Base Sepolia USDC payment has gone through. It takes about half an hour.
1. A server and DNS
Get an Ubuntu 24.04 server with a public IP (4 vCPU and 8 GB is plenty to start, from any provider). Then add two DNS records pointing at its IP:
| Record | Example | For |
|---|---|---|
A worker | worker.clicloud.app | The control plane calling the worker |
A *.apps | *.apps.clicloud.app | Every app's address |
2. Set up the host
On the server, clone the repository and run the setup script. It installs Docker, gVisor (the sandbox apps run in), BuildKit and Railpack, creates the apps network and sets the firewall:
git clone https://github.com/<you>/cli && cd cli
sudo deploy/host-setup.sh3. Start the worker
cp deploy/worker.env.example deploy/worker.env
openssl rand -hex 32 # the shared secret: paste it as CLI_WORKER_SECRET
nano deploy/worker.env # CLI_WORKER_PUBLIC_HOST, CLI_APP_DOMAIN, CLI_WAKE_UPSTREAM, ACME_EMAIL
docker compose -f deploy/worker.compose.yml --env-file deploy/worker.env up -dCLI_WAKE_UPSTREAM is your control plane's public URL (your Railway URL or console domain). The router on this server sends some requests there: waking sleeping apps, static sites, protected previews, paywalls and edge checks. It marks them with X-CLI-Route, so the control plane reads the visitor's address from X-Forwarded-Host even behind Railway's proxy.
The worker only runs requests signed with the shared secret, inside a short time window, and refuses replays, so it's safe to reach over HTTPS. If your control plane has fixed outbound IPs, you can also limit port 443 on CLI_WORKER_PUBLIC_HOST to them.
4. Point the control plane at it
Set these on the control plane (Railway → Variables) and redeploy it:
CLI_RUNTIME=remote
CLI_WORKER_URL=https://worker.clicloud.app
CLI_WORKER_SECRET=<the same secret>
CLI_APP_DOMAIN=apps.clicloud.app
CLI_NETWORK=eip155:84532
CLI_FACILITATOR_URL=https://x402.org/facilitator
CLI_TREASURY=<a wallet you control>eip155:84532 is Base Sepolia, and x402.org's facilitator settles testnet payments for free.
5. Check everything from one command
Run the launch checks where the control plane's variables are loaded (on Railway: railway run npm run preflight):
CLI_PREFLIGHT_PAYER_KEY=0x<a test wallet holding a little Base Sepolia USDC> npm run preflight| Check | Fix if it fails |
|---|---|
worker https://… | "not reachable": DNS or port 443. "refused CLI's signature": the two secrets differ |
| Public URL answers | CLI_PUBLIC_URL is wrong, or the control plane is down |
| App wildcard DNS | Add the *.apps record and wait for it to propagate |
| Testnet payment | The test wallet needs Base Sepolia USDC (free from Circle's faucet) |
The testnet payment check signs a real 0.01 USDC x402 payment from the test wallet to your treasury, and the facilitator verifies it. Add --settle to actually move it on chain, and check the transaction on Base Sepolia's explorer. On testnet, warnings are fine; failures aren't.
6. Deploy something and pay for it
- Sign in to the console, create a project, and add credit with Top up → Pay with crypto, using a wallet on Base Sepolia.
- Deploy
examples/or any repo. The app getshttps://<name>-<id>.apps.clicloud.appwith a certificate within a minute. - The project doctor at the top of the project should say everything looks good.
To run the same flow end to end automatically, use npm run smoke -- --api https://<your console> with CLI_SMOKE_WALLET_KEY set to the test wallet.
Next
More servers (regions) go in CLI_SERVERS, or connect out from any cloud with Add server (/docs/own-cloud). Before real money, follow the mainnet steps in Running CLI yourself: Coinbase's facilitator, CLI_NETWORK=eip155:8453, and npm run preflight printing Ready.