Skip to main content
A service is an HTTP server that runs beside the app on its own machine. Use one for work that does not fit a Pylon function:
  • a worker in Python, Go, or another language
  • a process that needs system packages or a browser
  • a long-running agent
You declare a service in app.ts. pylon deploy ships it with the app. Stack0 Cloud runs each service on a Fly Sprite, a Linux machine that sleeps when it is idle.

Declare a service

app.ts
An app can declare up to 8 services.

Call the service from the app

The app reads the URL and the token from its environment.
functions/measure.ts

Check the token in the service

The URL of a service is public. The service must check the token on each request, and it must compare it in constant time.
services/worker/worker/app.py
The host calls healthPath without the token. Do not return private data from it.

The environment of a service

The setup command and the start command see these variables: ~/.local/bin is on PATH, so tools that uv, pipx, and similar installers add are found. A service that reads a secret the project does not have stops the deploy. Set the secret first:

What a deploy does

  1. pylon deploy checks that each dir exists and that the project has each secret in env.
  2. The builder packs each dir. It leaves out .git, node_modules, .venv, and Python cache directories.
  3. Cloud installs each changed service beside the release that runs. It runs setup with outbound access to the package registries.
  4. When all services are installed, Cloud switches each one to the new release and restarts it.
  5. Cloud calls healthPath on each service. Each one has 3 minutes to answer.
  6. Cloud sets the URL and the token on the app and starts the new app version.
A deploy does not install a service again when its files, its declaration, and its environment are the same as the release that runs. A failed setup leaves the app and all services on the releases they had. A service that does not answer goes back to its release from before, and the deploy fails. The deployment page and pylon services show the install log.

Limit outbound access

allowHosts limits the hosts a service can connect to when it runs. The app is always allowed.
The limit is DNS-based. A host that is not on the list does not resolve.

Idle services

A service sleeps about 30 seconds after its last request. The next request wakes it in 1 to 2 seconds, or in less than a second when it slept a short time. Open connections drop when the machine sleeps. Set keepAwake: true for a service that must hold a connection open or must answer without the wake time. That service runs, and bills, all the time.

See and operate services

The project’s Services page in the dashboard shows the same data, with each deploy and its log. logs and restart need the owner role or the admin role.

Cost

Cloud bills a service for what it uses:
  • CPU time
  • memory, for the time the machine runs
  • disk
A sleeping service bills for disk only. The usage appears on the invoice as Cloud compute. Services need a paid plan.

Limits

  • A service is an HTTP server. It has one port.
  • Each service has its own machine and its own disk. The disk keeps files between deploys and restarts.
  • A rollback builds the earlier commit again, so it also puts the services back on that commit.
  • A preview environment does not get services, and it does not get the URL or the token of the project’s services.
  • pylon dev does not start services. Start each one yourself and set urlEnv and tokenEnv in .env.