On this page
Services
A service is a program that Kilby runs for you, from a container image that you name or that Kilby builds from your Git repository. There are four kinds. They share the same settings and the same API (/api/v1/services); the type field says which kind you are dealing with. Every service is also listed in an environment of a project, Production of the Default project unless you choose another one when you create it: that only organizes, and shares the workspace's limits and network (Projects and environments).
| Kind | API type | Reachable from | Port | Runs |
|---|---|---|---|---|
| Web Service | web | The internet, over HTTPS | Required | All the time |
| Private Service | private | Other services of the same workspace only | Required | All the time |
| Background Worker | worker | Nobody: it receives no traffic | None | All the time |
| Cron Job | cron | Nobody | None | On a schedule, then exits |
Where the image comes from#
A service runs an image you name, from a registry on the internet. A web service, a private service or a background worker can instead be built from a Git repository: Kilby builds the image itself and deploys it, and every build is listed under Deploys. A public repository needs only its address. A private one needs the GitHub connection. See Deploy from Git. A cron job always runs an image.
Web services#
A web service gets an HTTPS address of the form my-api-x7k2.apps.kilby.neuramorphic.ai: your service name, four random characters so the address cannot be guessed from the name, and Kilby's apps domain. Kilby terminates TLS for you. You can add your own domain too.
Your program must listen on 0.0.0.0 on the port you set, not only on localhost. Kilby also gives the port to your program in the PORT environment variable.
Private services#
A private service has no public address. Other services, workers and cron jobs of the same workspace reach it at <name>:<port>, for example http://vector-store:6333. Nothing outside the workspace can. Use it for a model server, a vector database, a cache or an internal API.
Background workers#
A worker runs all the time and takes no traffic: a queue consumer, an agent loop, a scheduler. It has no port and no health check. A worker whose command exits right after it starts makes the deploy fail, and the failed deploy says so. For work that runs and then stops, use a cron job.
Cron jobs#
A cron job runs its command on a schedule, in a fresh container each time.
- The schedule is five fields (minute, hour, day of month, month, day of week) in UTC, for example
0 3 * * *.@hourly,@daily,@weekly,@monthlyand@yearlywork too. - A run that takes longer than 1 hour is stopped.
- A failed run is not retried. It is marked failed and keeps its output. Kilby can email the workspace when a run fails (Webhooks and notifications).
- If a run is still going when the next one is due, the new one is skipped: runs never overlap.
- Click Trigger run to run it now. The Runs tab lists the last 10 successful and the last 10 failed runs, with their output.
- A cron job cannot have a disk or several instances, and it counts toward the workspace's cron job limit (see Limits and quotas).
Settings every service has#
| Setting | What it does |
|---|---|
| Name | 3 to 40 characters: lowercase letters, digits and single hyphens, starting with a letter. It cannot start with db- and kv- (reserved for databases and Key Value instances) and it cannot be changed later. |
| Container image | A reference such as ghcr.io/acme/api:1.4, from a registry on the internet. It must be built for linux/amd64. |
| Start command | Optional. Replaces the command built into the image. It runs with /bin/sh -c, so the image needs a shell. Up to 2000 characters. |
| Pre-deploy command | Optional. A command that runs once before each deploy, usually database migrations, with the new image and environment. If it fails, the deploy fails and the running version is not changed. It runs with /bin/sh -c, so the image needs a shell, and it may run more than once for the same version, so it must be safe to repeat. Up to 2000 characters, with a time limit of 10 to 1800 seconds. Not for cron jobs. See Pre-deploy command. |
| Port | The port your program listens on. Web and private services only. |
| Health check path | Optional, for web and private services. See below. |
| Instance type | CPU and memory. See below. |
| Environment | See Environment variables and secrets. Variables shared by several services can live in an environment group. |
| Read-only filesystem | Off unless you turn it on. When on, the container cannot write to its own filesystem: only in /tmp (an empty folder of up to 1 GB, emptied when an instance restarts) and on its disk, if it has one. It makes a compromised program harder to keep running, and images that write next to their code, or keep caches elsewhere, fail to start with it. In Settings, or read_only_root in the API; it changes with the deploy the change starts. |
The image check#
While you type an image, Kilby asks the image's registry whether it exists and shows what it found under the field: the digest, whether the image has a build Kilby can run, and its size. It also reads the port the image declares: one declared port is filled into Port for you, several are listed for you to pick from, and none is said plainly, because Kilby cannot guess it. The same check runs when you save, whether you use the dashboard, the API (POST /api/v1/images/check) or the CLI (kilby images check IMAGE). Kilby refuses to save an image that is certainly not usable: the image or the tag is not there, the registry credentials you picked were refused, or the image has no linux/amd64 build, which is the only platform Kilby runs. An image built on an Apple silicon laptop is arm64 only and is caught here instead of when the deploy fails.
What the check does not know: without credentials, a private image looks exactly like one that does not exist, so Kilby says both. When the registry does not answer, asks for a login or is limiting requests (Docker Hub limits anonymous clients), Kilby shows a calm note and refuses nothing: the deploy reports what happens. The answer is what the registry said a moment ago and is kept for a minute, so a tag that moves afterwards is not noticed. Only registries on the public internet are asked, and each person and each workspace can only check so often. Changing something other than the image or its credentials, such as the instance type or a variable, does not run the check, and the images of a template are not checked either.
Docker Hub images#
A service that uses a Docker Hub image and has no registry credentials downloads it, when you deploy, from Kilby's cache in Amazon ECR instead of from Docker Hub, so Docker Hub's limit on downloads from one address rarely slows a deploy. An image the cache does not hold yet is still fetched from Docker Hub once, and a tag that its publisher moves can reach the cache later than it reaches Docker Hub. A service with registry credentials downloads from Docker Hub itself. The dashboard, the API, the CLI and the deploy history keep showing the image name you wrote.
Private images#
A private image needs registry credentials: Registry credentials in the dashboard, or /api/v1/registry-credentials. Kilby supports GHCR, Docker Hub, GitLab and Quay. Private Amazon ECR is not supported yet, because its login tokens expire every 12 hours; ECR Public images work. Credentials are encrypted, shown once, and only usable for the registry they were made for. Pick them in the service settings.
Health checks#
Without a health check path, Kilby only checks that your program accepts connections on its port. A service gets up to 5 minutes to start listening, which is enough for a program that loads a large model first.
With a path such as /healthz, Kilby calls it with an HTTP GET on your port. A deploy goes live, and an instance receives traffic, only once the path answers with a 2xx or 3xx status. The service gets up to 5 minutes to pass it for the first time. After that it is checked every 5 seconds; an instance that fails 3 checks in a row stops getting traffic, and one that keeps failing for 60 seconds is restarted. The check sends the service's public host name in the Host header and X-Forwarded-Proto: https, so an app that redirects HTTP to HTTPS answers it normally.
Instance types#
The instance type sets the CPU and memory of every instance of the service. All of them are CPU only: GPU instance types are not available yet.
| Instance type | CPU | Memory | Web, private service, worker | Postgres (disk not included) |
|---|---|---|---|---|
starter | 0.5 | 512 MB | $9 a month | $14 a month |
standard | 1 | 2 GB | $25 a month | $40 a month |
pro | 2 | 4 GB | $85 a month | $75 a month |
Prices are list prices per instance. Kilby is free during the beta and nothing is billed today. The dashboard shows the list price next to each service, and the Usage page shows what your workspace would cost at list prices. Every form that creates or resizes something shows the price per month in a bar at the bottom while you fill it in: it adds up the instance type, the number of instances (the least and the most when a service autoscales) and the disk, shows the change in price when you resize, and says so when a change would not fit the workspace limits before you send it. A cron job is priced by the second it runs at the instance rate, with a minimum of $1 a month for as long as the job exists. Disk is $0.25 per GB a month for a service disk and $0.30 per GB a month for a database disk. GET /api/v1/pricing returns the same numbers as JSON without an API key.
Suspend, resume and delete#
- Suspend stops a service and keeps its settings, its address and its disk. A suspended cron job stops starting runs.
- Resume starts it again with its current settings. It must fit the workspace limits again.
- Delete removes the service and its address, and its disk with every file on it. This cannot be undone.
When a web service cannot answer#
A visitor of a web service that cannot answer gets a short page from Kilby instead of the gateway's bare error. The page is plain, small and loads from one request. It says only what a visitor needs to know, and never who owns the service, which workspace it is in, which image it runs or why it is down.
| When | The page says | Status |
|---|---|---|
| The service is suspended | This service is suspended | 503 |
| Maintenance mode is on | This service is under maintenance, and your message if you wrote one | 503 |
| The service is starting and no instance is ready yet | This service is starting. The page refreshes by itself. | 503 |
| No instance is ready and the service is not starting: it crashed, or never became ready | This service is not responding | 503 |
Every page carries a Retry-After header, so a program knows to wait, and may be cached for a few seconds. An instance that restarts in a moment does not change the page: a service shows "starting" or "not responding" only after it has had no ready instance for a few seconds. A service that answers is never touched. If your own program sends a 503 or a 404, with its own body, a visitor gets exactly that. The same pages are shown on the service's custom domains.
An address that no service uses, and a service that was deleted, still answer with an empty 404 from the gateway.
Maintenance mode#
Maintenance mode shows the maintenance page to every visitor while your instances keep running. Nothing is deployed or restarted, and turning it off serves the service again.
- Turn it on and off in the service's Settings, under Maintenance mode, or with
PUT /api/v1/services/{id}/maintenance({"enabled": true, "message": "..."}). It needs the Developer role or higher. - The message is optional: plain text of up to 280 characters, shown below the heading. It is never read as HTML. It is kept while maintenance mode is off, so you do not retype it.
- It takes effect within a few seconds, in both directions. The service's header shows a Maintenance badge, the services list says "Maintenance mode", and the API says
"maintenance": true. - Only web services have it: they are the ones with a public address. A suspended service shows the suspended page, whatever else is set.
- Turning it on, off or changing the message is recorded in the workspace's Activity.
Related#
- Environment variables and secrets: configure a service.
- Templates: services that Kilby creates for you from a ready-made recipe.
- Deploys, rollbacks and downtime: what happens when a service changes.
- Disks and scaling: persistent storage, several instances and autoscaling.
- Limits and quotas: how many services a workspace can run.