#nix #docker #compose #supervisor #cli


Define and run multi-service applications on isolated environments with Nix or Docker

1 unstable release

0.1.0 May 23, 2023

#21 in #supervisor

Used in 6 crates (4 directly)

MPL-2.0 license

60 lines


License: MPL-2.0 release discord-server

Superviseur is a tool for running multi-service applications on isolated environments (Nix or Docker) using HCL/TOML or any language with an SDK. It is designed to be used both from a CLI and a web interface. Once you have a Superfile.hcl, you can create and start your application with a single command: superviseur up.

Project Status: 🐲 Unstable, alpha-ish quality.

🚚 Installation

Compiling from source, without Nix:

# Install dependencies
brew install protobuf # macOS
sudo apt-get install -y protobuf-compiler # Ubuntu/Debian
curl -fsSL https://bun.sh/install | bash
# Compile
git clone https://github.com/tsirysndr/superviseur.git
cd superviseur/crates/webui/webui && bun install && bun run build && cd ../../../
cargo install --path crates/cli

with Nix:

git clone https://github.com/tsirysndr/superviseur.git
cd superviseur
nix develop --experimental-features "nix-command flakes" flake/
cd crates/webui/webui && bun install && bun run build && cd ../../../
cargo install --path crates/cli


Using Homebrew:

brew install tsirysndr/tap/superviseur

Or download the latest release for your platform here.

📦 Downloads

🚀 Usage

    superviseur [SUBCOMMAND]

    -h, --help       Print help information
    -V, --version    Print version information

    build         Build all services or a specific one
    config        Get the config of a service
    daemon        Start the superviseur daemon
    down          Stop all services
    help          Print this message or the help of the given subcommand(s)
    init          Create a new superviseur config (Superviseur.hcl)
    list          List all services [aliases: ls]
    log           Get the log of a process
    new           Create a new superviseur config (Superviseur.hcl)
    open          Open URL of a service in the browser
    project       Manage projects
    ps            List all running processes
    restart       Restart all services or a specific one
    search-log    Search the log of a service
    serve         Start the superviseur server
    start         Start all services or a specific one
    status        Get the status of a service
    stop          Stop all services or a specific one
    tail          Tail the log of a process
    ui            Start the superviseur dashboard
    up            Start all services

📚 Getting Started

Start the server

Superviseur uses a server-client architecture. The server is responsible for managing the processes, while the client is responsible for communicating with the server.

superviseur daemon

Initialize a new project

superviseur new

Start by initializing a new project. This will create a Superfile.hcl file in the current directory with the following contents:

project = "demo"

service "demo" {
  type = "exec"
  command = "ping $GITHUB_DOMAIN"
  working_dir = "/tmp"
  description = "Ping Service Example"
  depends_on = []
  env = {
    "GITHUB_DOMAIN" = "github.com"
  stdout = "/tmp/demo-stdout.log"
  stderr = "/tmp/demo-stderr.log"

Start the service

superviseur start demo

Start the service by running the start command.

Check the status

superviseur status demo


● demo - Ping Service Example
        Active: Running since 2023-03-05 19:17:56.512455 UTC; 17 seconds ago
           PID: 30887
       Command: ping $GITHUB_DOMAIN
     Directory: /tmp
           Log: /tmp/demo-stdout.log
        Stderr: /tmp/demo-stderr.log
   AutoRestart: false
          Type: exec
          Envs: GITHUB_DOMAIN=github.com

Show running processes

superviseur ps


 NAME   PID     STATUS             COMMAND               TYPE 
 demo   31200   Up 4 seconds ago   ping $GITHUB_DOMAIN   exec 

Stop the service

superviseur stop demo

Show all services

superviseur ls


 NAME   STATUS    COMMAND                 TYPE 
 demo   STOPPED   "ping $GITHUB_DOMAIN"   exec 

As a Github Action

You can use the setup-superviseur Github Action like so:

- uses: tsirysndr/setup-superviseur@v1
    version: 'v0.1.0-alpha.13'
- run: superviseur --help

📖 Examples

See the examples directory for more examples.

📝 License


No runtime deps