1. Add the workload
In a new folder, or in an existing project:Output
--runtime is node, python or rust. init writes:
The table it writes:
run starts the service. Its paths are relative to workloads/api/, so this one runs workloads/api/index.js. resource_class is the size of machine it runs on, and route = "/*" sends every path on the owning actor’s address to the service.
2. Add your service
Put your service’s code inworkloads/api/, with the entry file that run names, here index.js. A Python service uses ["python", "main.py"], and a Rust service names its binary, such as ["bin/server"].
The service must:
- Listen on all interfaces, on the port in the
PORTenvironment variable (8080 when it’s unset). - Answer HTTP requests there.
- Answer
GET /_cowboy/healthwith200once it is ready to serve, and only then.
PORT=8080 node index.js (or python main.py) in workloads/api/, then curl http://localhost:8080/_cowboy/health.
Everything in workloads/api/ ships with the service. To add a build step, set build in the table (every key). A Python service with dependencies needs one, and init leaves an example as a comment in the table.
3. Check it
Output
actor pays means visitors pay nothing for requests to the route.
4. Deploy it
Output
deploy goes through four steps:
- Checks that the network can run your service, and stops if not.
- Works out the cost, including a deposit, and stops if your wallet can’t cover it.
- Deploys the owning actor, if it isn’t deployed yet, with the route.
- Builds and publishes the service, and a runner starts it.
Gateway line), and whether a runner has started the workload yet.
After you change the service, run cowboy deploy api again. It keeps the owning actor as it is, at the same address and URL.
5. Open it to visitors
The route starts owner-only. When your service is ready for everyone, publish the owning actor’s site:Output
--owner-only closes it again. Once the workload is running, open the Gateway URL, or curl it:
Output
cowboy actor inspect api_owner shows the URL again.
Operate it
Requests to the workload don’t run the owning actor, so they don’t draw on its balance.
Settings, storage and secrets
vars in the workload’s table sets environment variables, such as vars = { LOG_LEVEL = "info" }. Anyone can read them, so never put credentials there: add those to the secret store (cowboy secrets). For storage, [[workloads.<name>.mounts]] mounts a storage volume into the service (every key).