ubermind

A native Rust process supervisor for managing multiple projects. Each project keeps its own Procfile, and ubermind orchestrates them all from anywhere with auto-restart, log management, and live monitoring.

Inspired by overmind and foreman.

Install

# shell script (prebuilt binary)
curl -fsSL https://raw.githubusercontent.com/mrgnw/ubermind/main/install.sh | sh

# gah (github asset helper)
gah install mrgnw/ubermind

# cargo
cargo install ubermind       # from source
cargo binstall ubermind      # prebuilt binary

Shell completion

Tab completion for commands, project names, and flags:

ub start appli<tab>    # completes to: ub start appligator
ub st<tab>             # completes to: ub status / ub start / ub stop
ub status <tab>        # shows all project names

Setup:

If installed via the install script, completions are in ~/.local/share/ubermind/completions/.

Bash:

echo 'source ~/.local/share/ubermind/completions/ub.bash' >> ~/.bashrc

Zsh:

# Add to ~/.zshrc
fpath=(~/.local/share/ubermind/completions $fpath)
autoload -Uz compinit && compinit

Fish:

ln -s ~/.local/share/ubermind/completions/ub.fish ~/.config/fish/completions/

Quick start

1. Initialize ubermind

ubermind init

This creates a projects config at ~/.config/ubermind/projects.

2. Create a Procfile in your project

Each project you want to manage needs a Procfile in its root directory. A Procfile lists the processes to run — one per line, in name: command format:

# ~/dev/myapp/Procfile
web: npm run dev
api: python server.py
worker: ruby worker.rb

This is the standard Procfile format. Each line becomes a named process that ubermind will manage.

3. Register your project with ubermind

ubermind add myapp ~/dev/myapp

This tells ubermind "there's a project called myapp at ~/dev/myapp that has a Procfile."

Shorthand: If you're already in the project directory with a Procfile, just run:

cd ~/dev/myapp
ubermind add
# myapp: added (/Users/you/dev/myapp)

This automatically uses the directory name as the project name.

4. Start it

ubermind start myapp    # start one project
ubermind start          # or start everything

How it fits together

ubermind has two layers of config:

Projects file (~/.config/ubermind/projects) — maps project names to directories:

myapp: ~/dev/myapp
api: ~/dev/api-server
frontend: ~/dev/frontend

Commands file (~/.config/ubermind/commands) — optional, defines standalone commands in Procfile format:

tunnel: ssh -N -L 5432:localhost:5432 prod-server
sync: watchman-wait . --max-events 0 -p '*.json' | xargs ./sync.sh

Each project directory has its own Procfile that defines what processes to run:

# ~/dev/myapp/Procfile
web: npm run dev
api: python server.py

# ~/dev/api-server/Procfile
server: cargo run
worker: cargo run --bin worker

# ~/dev/frontend/Procfile
dev: pnpm dev

When you run ubermind start myapp, ubermind looks up myapp → ~/dev/myapp, then starts its daemon in that directory using the Procfile. Each project gets its own isolated supervisor instance — one project crashing won't affect the others.

Standalone commands from the commands file are auto-expanded into generated Procfiles under ~/.config/ubermind/_commands/.

Usage

ubermind init                # create projects config file
ubermind add [name] [dir]    # register a project directory (uses cwd if omitted)

ubermind status              # show all projects
ubermind start [name]        # start project(s)
ubermind stop [name]         # stop project(s)
ubermind reload [name]       # restart project(s) (picks up Procfile changes)
ubermind kill [name]         # kill process(es) in project(s)
ubermind restart [name]      # restart process(es) in project(s)
ubermind echo [name]         # live stream logs from project(s)
ubermind logs [name]         # show last 100 lines of log file
ubermind tail [name]         # follow log file (tail -f)
ubermind serve [-p PORT]     # start web UI server (default port: 13369)

Watch mode

Commands that modify services automatically watch status for 4 seconds:

ubermind start myapp               # starts and watches for 4 seconds
ubermind stop myapp                # stops and watches for 4 seconds
ubermind reload myapp              # reloads and watches for 4 seconds
ubermind restart myapp web         # restarts process and watches for 4 seconds

Override the default watch duration or use with status:

ubermind status --watch            # watch indefinitely (refreshes every 1s)
ubermind status --watch 10         # watch for 10 seconds
ubermind start myapp --watch 8     # start and watch for 8 seconds (overrides default)
ubermind reload myapp --watch 0    # reload without watching

Live logs

ubermind echo myapp          # live stream logs from myapp (runs until stopped)
ubermind echo myapp web      # live stream from specific process
ubermind logs myapp          # show last 100 lines from log file
ubermind tail myapp          # follow log file (like tail -f)

Targeting

Pass project names to target specific projects:

ubermind status myapp        # show status of myapp
ubermind myapp status        # same thing, flexible arg ordering

Omit the name to target all projects (or current project if in a registered directory):

ubermind start               # start all projects
ubermind stop                # stop all projects
cd ~/dev/myapp && ub status  # show status of myapp (context-aware)

Config

The projects file lives at ~/.config/ubermind/projects (respects $XDG_CONFIG_HOME).

You can edit it directly or use ubermind add:

# name: directory
myapp: ~/dev/myapp
api: ~/dev/api-server
frontend: ~/dev/frontend

Quick add from a project directory:

cd ~/dev/myapp && ubermind add              # infers name from directory
cd ~/dev/myapp && ubermind add myapp        # uses cwd, custom name
ubermind add myapp ~/dev/myapp              # full form with explicit path

Optionally, define standalone commands in ~/.config/ubermind/commands:

tunnel: ssh -N -L 5432:localhost:5432 prod-server
sync: watchman-wait . --max-events 0 -p '*.json' | xargs ./sync.sh

See tmux cheatsheet for navigating connected sessions (scrolling, copying error text, etc).

How it works

ubermind uses native Rust process supervision with:

• Direct PID-based process management
• Auto-restart on crash with configurable retry limits
• Log files with rotation (stored in ~/.local/share/ubermind/log/)
• Live log streaming via ring buffers
• Unix socket communication for CLI commands
• HTTP/WebSocket API for the web UI

Each project directory gets its own independent supervisor instance. ubermind knows where each project lives and dispatches commands to the right supervisor.

Standalone commands are auto-expanded into generated Procfiles under ~/.config/ubermind/_commands/ (an internal directory that you shouldn't edit directly).

License

MIT

History

ubermind v0.6+ uses native Rust process management. Earlier versions (v0.1-v0.5) were thin wrappers around overmind and tmux.