Serverlet

Introduction

A serverlet is Futrou’s compute unit — the thing that actually runs your application. It’s a managed, auto-scaling container with a serverless-like experience: you give it a container image and choose how much CPU and RAM it gets, and Futrou takes care of running it, keeping it alive, and scaling it up or down with load. Each serverlet runs inside isolated microVM, so it never shares a kernel with another workload.

Over its lifetime, a serverlet has zero, one, or more running instances — it can scale down to zero when idle and back up to many under load, all without you managing the machines underneath.

If you’ve used a container platform before, a serverlet is closest to a managed container service: you’re not managing a VM or a bare server, and you’re not writing Kubernetes manifests either. You bring an image, Futrou runs it.

Creating a serverlet

Creating a serverlet takes a name, an image, an architecture, and a plan. You can adjust scaling and everything else afterwards.

• Region — where the serverlet runs, or Auto to let Futrou choose.
• Serverlet Name — used in the dashboard and in the generated internal domain.
• Architecture — AMD64 or ARM64, depending on your image.
• Image — any Docker image, defaulting to futrou/serverlet:latest.
• Min / Max Instances — the instance range for autoscaling; set both to the same value for a fixed instance count.
• Serverlet Plan — the CPU and RAM tier. See Plans.

Image

Every serverlet runs a Docker image — either one of your own, published to any registry, or a Futrou base image you build on top of. There’s no buildpack step and no source upload: if it runs as a container, it runs as a serverlet. An image can be up to 3 GiB — see Limits for this and other platform-wide numeric limits.

Plans

Every serverlet runs on a plan — a fixed tier of CPU and RAM. Larger plans cost more per minute but handle more load per instance.

• CPU — the guaranteed compute power for the serverlet, expressed in vCPUs. A value of 0.5 means a guaranteed 50% of one vCPU’s compute time. This is a guarantee, not a ceiling — if the underlying host has spare capacity, your serverlet may burst above it.
• RAM — the maximum memory available to the serverlet, reserved and guaranteed for its exclusive use.
• Choosing a plan — smaller plans suit static sites, lightweight APIs, and background workers. Larger plans suit applications with real request volume or in-memory workloads like caches and databases. If you’re not sure, start small — you can change a serverlet’s plan at any time, and combine it with autoscaling to add instances under load instead of sizing a single instance for peak traffic. For current plan names, exact CPU/RAM figures, and pricing, check the plan selector when creating or editing a serverlet in the dashboard — pricing is shown per minute and as an estimated monthly cost before you confirm.
• Billing — serverlets are billed per minute of uptime, at the rate of the selected plan, deducted from your workspace credit balance. A stopped serverlet isn’t billed. If a serverlet runs multiple instances, each instance is billed separately.

ENV

Configuration is passed in through environment variables, set either on the serverlet itself or shared across the whole project. Project-level variables apply to every serverlet in the project; serverlet-level variables override them when both define the same key. Variables can be marked as secret, which hides their value in the dashboard.

Futrou also injects a few variables automatically so your application can identify where it’s running: FUTROU_WORKSPACE, FUTROU_PROJECT, and FUTROU_SERVERLET.

Mounts

A serverlet can mount one or more storages, each attached as a block device at a path you choose inside the container. A given storage can be mounted at exactly one path on a serverlet — a storage referenced twice with two different destinations isn’t a supported configuration, since a mount is a single {storage: path} pairing. The same storage can still be mounted into other serverlets, or other instances, independently; see Storage → Mounting into serverlets.

Once mounted, it’s a real local filesystem, so your application can create and follow symlinks inside it like any other directory — that’s different from the storage’s S3-compatible and Storage APIs, which never follow a symlink at all.

Logs

From the serverlet’s page in the dashboard you can stream and search logs across every instance in real time. See Logs for what’s captured.

Metrics

The serverlet’s page also shows real-time CPU, RAM, and network metrics, and a browser-based console for a shell inside a running instance — no SSH client or key setup required.

Region

Serverlets run in a specific region, or you can leave it on Auto and let Futrou pick one for you. Proxies and DNS zones in the same project are typically placed in the same region for the shortest path between them.

Actions

A serverlet can be managed from its page in the dashboard, either as a whole or per instance:

• Start — brings it back up on the same image and settings as before.
• Stop — keeps its configuration and doesn’t delete anything; nothing is billed while stopped.
• Restart — a stop followed by a start. If your application doesn’t shut down cleanly, a restart can interrupt in-flight requests, so redeploy through a new image or config change where possible rather than restarting to pick up changes.

Scaling

A serverlet can run as more than one instance at once. Scaling is configured with four values: Min Instances, Max Instances, and CPU/RAM scaling thresholds (as a percentage, default 75%). When average usage across running instances crosses a threshold, Futrou adds an instance, up to the maximum; when usage drops, it removes one, down to the minimum.

Set Min and Max to the same number to disable autoscaling and keep a fixed instance count.

Scaling to zero

Setting Min Instances to 0 allows a serverlet to scale all the way down when it’s idle — no instances running, nothing billed. When a request arrives at the proxy for a serverlet with no running instances, Futrou starts one and holds the request open while it boots. If the instance becomes ready within 20 seconds, that first request is forwarded to it and the caller sees a normal response, just a little slower. If it isn’t ready in time, the proxy returns a 504 Gateway Timeout — the client (or your own retry logic) needs to send the request again, by which point the instance is typically already up.

This makes scale-to-zero a good fit for low-traffic or internal services where an occasional slow first request is acceptable, and a poor fit for anything that can’t tolerate a cold-start delay on its first request after idling.

Rolling updates

Changing a serverlet’s image, plan, or environment variables triggers a rolling update — old and new instances run side by side, and traffic shifts over without downtime. New instances are started in batches (a quarter of your max instance count at a time, at least one), and old instances are removed oldest-first as new ones take over. An old instance stops accepting new requests once it’s due for replacement, but is given a short grace period to finish requests already in flight before it’s stopped.

Changing routing-only settings — ports, volumes, or the min/max instance counts themselves — doesn’t trigger a rolling update, since there’s no new image or config for instances to roll onto; those changes apply in place.

Syncing configuration

Most changes — image, plan, instance count, environment variables — take effect automatically. If a serverlet ever looks out of sync with its saved configuration, a manual sync action re-applies it.

Getting online

A newly created serverlet isn’t reachable from the internet by itself — it needs a proxy in front of it. Futrou creates one automatically when you create a serverlet, publishing it at a generated *.futrou.cloud address. You can add your own domain, adjust routing, or create additional proxies at any time; see Proxy for details.