Skip to main content
This page puts your own long-running service on Cowboy, at a URL anyone can reach once you open it. Such a service is called a workload. You write it in Node, Python or Rust, and an actor owns it. A runner, a machine that does work for actors, runs it and keeps it up, and requests to the owning actor’s URL go to the service. First, install the CLI. To deploy, you also need a funded wallet on Cloud.

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.
Decide the owning actor’s code and routes before the first deploy. After it, a deploy updates the workload, not the actor, and refuses a changed route. The workload itself you can change and redeploy as often as you like.

2. Add your service

Put your service’s code in workloads/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 PORT environment variable (8080 when it’s unset).
  • Answer HTTP requests there.
  • Answer GET /_cowboy/health with 200 once it is ready to serve, and only then.
A minimal service that does all three:
Try it on your machine with 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:
  1. Checks that the network can run your service, and stops if not.
  2. Works out the cost, including a deposit, and stops if your wallet can’t cover it.
  3. Deploys the owning actor, if it isn’t deployed yet, with the route.
  4. Builds and publishes the service, and a runner starts it.
The output gives the owning actor, its URL (the 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).

List it in the General Store

To let others hire your app, list the owning actor: submit it on Cloud.

Next