sablier

Free and open-source software that starts workloads on demand and stops them after a period of inactivity.

It integrates with reverse proxy plugins (Traefik, Caddy, Nginx, Envoy, etc.) to intercept incoming requests, wake up sleeping workloads, and display a waiting page until they're ready.

Whether you're running on a resource-constrained device like a Raspberry Pi, managing a QA environment used only once a week, or reducing cloud costs by scaling idle workloads to zero — Sablier is built for you.

Key features:

• On-demand start/stop for Docker, Kubernetes, Podman, and Proxmox LXC workloads
• Customizable waiting UI with themes while workloads warm up
• Webhook notifications when instances start or stop
• Prometheus metrics for monitoring session and workload activity
• OpenTelemetry tracing for end-to-end request observability
• Stop or pause strategies to maximize resource reclamation on constrained hardware
• Scale mode: throttle CPU and memory when idle instead of stopping, for zero-cold-start workloads
• Anti-affinity: make a workload back off automatically while another group is active, to avoid GPU/RAM contention

---

• Installation
  • Use the Docker image
  • Use the binary distribution
  • Compile your binary from the sources
  • Use the Helm Chart
• Quick Start
• Configuration
  • Configuration File
  • Environment Variables
  • Arguments
• Providers
  • Docker
  • Docker Swarm
  • Podman
  • Kubernetes
  • Proxmox LXC
• Scale Mode
• Webhooks
• Observability
  • Metrics
  • Tracing
• Performance
• Usage with Reverse Proxies
  • Apache APISIX
  • Caddy
  • Envoy
  • Istio
  • Nginx
  • Traefik
• Community
• Support
• Sponsor
  • DigitalOcean

Installation

You can install Sablier using one of the following methods:

• Use the Docker image
• Use the binary distribution
• Compile your binary from the sources
• Use the Helm Chart

Use the Docker image

• Docker Hub: sablierapp/sablier
• GitHub Container Registry: ghcr.io/sablierapp/sablier

With Docker Compose — copy this into a compose.yaml and run docker compose up -d:

services:
  sablier:
    image: sablierapp/sablier:1.18.0 # x-release-please-version
    command:
      - start
      - --provider.name=docker
    ports:
      - "10000:10000"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

With docker run — using a sample configuration file (sablier.yaml):

docker run -p 10000:10000 -v /var/run/docker.sock:/var/run/docker.sock sablierapp/sablier:1.18.0

[!TIP] Verify the image signature to ensure authenticity:

gh attestation verify --owner sablierapp oci://sablierapp/sablier:1.18.0

Use the binary distribution

Grab the latest binary from the releases page and run it:

./sablier --help

[!TIP] Verify the binary signature to ensure authenticity:

gh attestation verify sablier-1.10.3-linux-amd64.tar.gz -R sablierapp/sablier

Compile your binary from the sources

git clone [email protected]:sablierapp/sablier.git
cd sablier
make
# Output will change depending on your distro
./sablier_draft_linux-amd64

Use the Helm Chart

Deploy Sablier to your Kubernetes cluster using the official Helm chart for production-ready deployments.

Add the Sablier Helm repository:

helm repo add sablierapp https://sablierapp.github.io/helm-charts
helm repo update

Install Sablier:

helm install sablier sablierapp/sablier

Full Documentation | Chart Repository

---

Quick Start

[!NOTE] This quick start demonstrates Sablier with the Docker provider.

For other providers, see the Providers section.

1. Start your container to scale to zero

Run your container with Sablier labels:

docker run -d --health-cmd "/mimic healthcheck" -p 8080:80 --name mimic \
  --label sablier.enable=true \
  --label sablier.group=demo \
  sablierapp/mimic:v0.3.3 \
  -running -running-after=5s \
  -healthy=true -healthy-after=5s

Here we run sablierapp/mimic, a configurable web-server for testing purposes.

[!CAUTION] You should always use a healthcheck with your application that needs to be scaled to zero.

Without a healtheck, Sablier cannot distinguish a started container from a container ready to receive incoming requests.

2. Stop the Container

Stop the container to simulate a scaled-down state:

docker stop mimic

[!TIP] Sablier can automatically stop containers at startup using the --provider.auto-stop-on-startup flag, which will stop all containers with sablier.enable=true labels.

3. Start Sablier

Start the Sablier server with the Docker provider:

docker run --name sablier \
  -p 10000:10000 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  sablierapp/sablier:1.10.5 \
  start --provider.name=docker

4. Request a Session

Call the Sablier API to start a session for the demo group:

curl -v http://localhost:10000/api/strategies/blocking\?group\=demo\&session_duration\=20s
* Request completely sent off
< HTTP/1.1 200 OK
< X-Sablier-Session-Status: ready

Sablier will start the mimic container automatically for 20 seconds..

[!TIP] Check out the Usage with Reverse Proxies section to integrate Sablier with Traefik, Caddy, Nginx, and more.

5. Verify the Container is Running

docker ps | grep mimic

6. Wait for Session Expiration

After the session duration (20 seconds in this example), Sablier will automatically stop the container.

# Wait 20 seconds, then check
docker ps -a | grep mimic

The container should be stopped.

---

Configuration

Full Documentation

There are three ways to configure Sablier:

1. In a configuration file
2. As environment variables
3. As command-line arguments

Configuration sources are evaluated in the order listed above with later methods overriding earlier ones.

If no value is provided for a given option, a default value is used.

Configuration File

At startup, Sablier searches for a configuration file named sablier.yml (or sablier.yaml) in:

• /etc/sablier/
• $XDG_CONFIG_HOME/
• $HOME/.config/
• . (the working directory)

You can override this using the configFile argument.

sablier --configFile=path/to/myconfigfile.yml

…

Environment Variables

Environment variables follow the same structure as the configuration file and are prefixed with SABLIER_. For example:

strategy:
  dynamic:
    custom-themes-path: /my/path

becomes

SABLIER_STRATEGY_DYNAMIC_CUSTOM_THEMES_PATH=/my/path

Arguments

To list all available arguments:

sablier --help

# or

docker run sablierapp/sablier:1.18.0 --help

Command-line arguments follow the same structure as the configuration file. For example:

strategy:
  dynamic:
    custom-themes-path: /my/path

becomes

sablier start --strategy.dynamic.custom-themes-path /my/path

Providers

Docker

Sablier integrates seamlessly with Docker Engine to manage container lifecycle based on demand.

Features:

• Connects to the Docker socket
• Starts/Stops containers
• Compatible with Docker Compose

Full Documentation

---

Docker Swarm

Sablier supports Docker Swarm mode for managing services across a cluster of Docker engines.

Features:

• Connects to the Docker socket (Manager node)
• Scales services to 0 and back
• Compatible with Docker Stack

Full Documentation

---

Podman

Sablier works with Podman, the daemonless container engine, providing the same dynamic scaling capabilities as Docker.

Features:

• Connects to the Podman socket
• Starts/Stops containers
• Supports rootless containers

Full Documentation

---

Kubernetes

Sablier provides native Kubernetes support for managing deployments, scaling workloads dynamically.

Features:

• Connects to the Kubernetes API
• Scales Deployments and StatefulSets to 0 and back
• Supports in-cluster and out-of-cluster configuration

Full Documentation

---

Proxmox LXC

Sablier supports Proxmox VE for managing LXC containers on demand via the Proxmox API.

Features:

• Connects to the Proxmox VE API with token authentication
• Starts/Stops LXC containers
• Discovers containers by sablier tag

Full Documentation

---

Systemd

Sablier integrates with systemd to manage units on demand, including per-user services when needed.

Features:

• Connects to the systemd D-Bus
• Starts/stops explicitly opted-in systemd units
• Supports system or user instances

Full Documentation

Scale Mode

By default, Sablier stops (or pauses) workloads when a session expires and restarts them on the next request. Scale mode is an alternative: instead of stopping a container, Sablier throttles its CPU, memory, and (on Docker) block I/O to a minimal idle allocation, then restores full resources the moment a new session arrives.

Because the container never stops, there is no cold-start latency — ideal for resource-constrained environments like a Raspberry Pi where you want to reclaim most of the hardware while keeping response times acceptable.

Scale mode is controlled entirely through labels:

labels:
  - "sablier.enable=true"
  - "sablier.group=myapp"
  # Idle state: keep running but throttle resources
  - "sablier.idle.replicas=1"
  - "sablier.idle.cpu=0.1"
  - "sablier.idle.memory=64m"
  # Active state: full resources when a session is requested
  - "sablier.active.replicas=1"
  - "sablier.active.cpu=2.0"
  - "sablier.active.memory=512m"

Label	Description
sablier.idle.replicas	Replica count while idle. Set to 0 to stop (default behaviour), 1+ to keep running.
sablier.idle.cpu	CPU limit while idle (e.g. 0.1 for 10% of one core). Requires idle.replicas >= 1.
sablier.idle.memory	Memory limit while idle (e.g. 64m). Requires idle.replicas >= 1.
sablier.active.replicas	Replica count when a session is active.
sablier.active.cpu	CPU limit restored when a session is active.
sablier.active.memory	Memory limit restored when a session is active.
sablier.idle.blkio-weight / sablier.active.blkio-weight	Block I/O weight 10–1000 (Docke