# zinit
A lightweight process supervisor with dependency management, similar to systemd but simpler.
## Quick Install
Get started in one command:
```bash
Or download and run the installer script directly:
```bash
cd /tmp && curl -O https://raw.githubusercontent.com/threefoldtech/zinit/main/scripts/install.sh
chmod +x install.sh
./install.sh
```
This will:
- Detect your OS and architecture
- Download pre-built binaries (Linux amd64, macOS arm64)
- Install to `$HOME/hero/bin`
- Configure your shell PATH automatically
- Start `zinit-server` in background (macOS/Windows only)
Then use: `zinit list`, `zinit status`, `zinit start <service>`, etc.
For more options, see [Quick Start](#quick-start) section below.
---
## Features
- **Dependency Graph**: Services declare dependencies (`requires`, `after`, `wants`, `conflicts`)
- **State Machine**: 7 explicit states (Inactive, Blocked, Starting, Running, Stopping, Exited, Failed)
- **Process Groups**: Signals sent to process groups, handling `sh -c` child processes correctly
- **Health Checks**: TCP, HTTP, and exec-based health checks with retries
- **Ordered Shutdown**: Dependents stop before their dependencies
- **Hot Reload**: Reload configuration without full restart
- **Multi-Environment**: Works in containers, VMs, and bare-metal
## Deployment Modes
zinit adapts its behavior based on deployment environment:
### Container Mode
Use `zinit-pid1` as your container entrypoint:
```dockerfile
ENTRYPOINT ["/usr/bin/zinit-pid1", "--container"]
```
Or set the environment variable:
```bash
ZINIT_CONTAINER=1 zinit-pid1
```
Behavior:
- Loads services from `/etc/zinit/services/`
- Clean exit on shutdown (no reboot syscall)
- No system services directory
### VM / Bare-Metal Mode
Use `zinit-pid1` as your init system (PID 1):
```
# In /sbin/init or kernel cmdline: init=/usr/bin/zinit-pid1
```
Behavior:
- Loads system services from `/etc/zinit/system/` first (auto-assigned `class=system`)
- Loads user services from `/etc/zinit/services/` second
- Handles reboot/poweroff via syscalls (SIGINT=reboot, SIGTERM=poweroff)
- Never exits (kernel panic prevention)
### Standalone Mode
Run `zinit-server` directly (not as PID 1):
```bash
zinit-server --config-dir /etc/zinit/services
```
Optionally enable system services directory:
```bash
zinit-server --config-dir /etc/zinit/services --pid1-mode
```
## Quick Start
### Installation (Recommended)
Download and install pre-built binaries:
```bash
./scripts/install.sh
```
This script:
- Detects your OS and architecture
- Downloads binaries from Forgejo registry
- Installs to `$HOME/hero/bin`
- Configures your PATH automatically
- On macOS/Windows, automatically starts the server in the background
### Building from Source
```bash
# Full build with Makefile
make build
# Or manual build
cargo build --release --features full
cargo build --release --features client # CLI only
cargo build --release --features server # Server only
# Run the server
zinit-server --config-dir /etc/zinit/services
# Use the CLI
zinit list
zinit status my-service
zinit start my-service
zinit stop my-service
```
See [scripts/README.md](scripts/README.md) for detailed information about installation scripts and the [Makefile](Makefile) for build targets.
## Architecture
```
zinit-pid1 (PID 1 shim)
| spawns/monitors
v
zinit-server (daemon)
| unix socket
v
zinit (CLI/TUI)
```
### Crate Structure
zinit is a single crate with feature flags:
```
src/
lib.rs # Library entry point
bin/
zinit.rs # CLI binary
zinit-server.rs # Server binary
zinit-pid1.rs # PID 1 binary (Linux only)
sdk/ # Shared types, config, protocol, clients
server/ # Supervisor, dependency graph, process management
client/ # CLI interface
```
### Features
| `client` | CLI interface |
| `server` | Supervisor daemon |
| `pid1` | PID 1 init shim (Linux only) |
| `tui` | Terminal UI for client |
| `rhai` | Rhai scripting support |
| `async` | Async client support |
| `full` | Build everything |
Default features: `client`, `server`
## Configuration
Service configs are TOML files in the config directory (default: `/etc/zinit/services/`).
**For detailed service configuration defaults and specifications, see [docs/SERVICE_SPECS.md](docs/SERVICE_SPECS.md)**
```toml
[service]
name = "my-app"
exec = "/usr/bin/my-app --daemon"
dir = "/var/lib/my-app" # optional working directory
oneshot = false # exit after success (default: false)
[dependencies]
requires = ["database"] # must be running
after = ["logger"] # start order only
wants = ["metrics"] # soft dependency
conflicts = ["legacy-app"] # mutual exclusion
[lifecycle]
start_timeout_ms = 30000
stop_timeout_ms = 10000
restart_delay_ms = 1000
restart_delay_max_ms = 60000
max_restarts = 0 # 0 = unlimited
[health]
type = "http"
endpoint = "http://localhost:8080/health"
interval_ms = 10000
retries = 3
[logging]
buffer_lines = 1000
```
### Targets
Virtual services for grouping:
```toml
[target]
name = "multi-user"
[dependencies]
requires = ["network", "logger", "database"]
```
### Service Status
The `status` field controls supervisor behavior:
- `start` (default): Automatically start and keep running
- `stop`: Keep stopped (won't auto-start)
- `ignore`: Supervisor ignores this service
### Service Class
The `class` field protects critical services from bulk operations:
- `user` (default): Normal service, affected by `*_all` commands
- `system`: Protected service, skipped by bulk operations
System-class services are immune to `start_all`, `stop_all`, and `delete_all` commands.
## CLI Commands
```bash
zinit list # List all services
zinit status <name> # Show service status
zinit start <name> # Start a service
zinit stop <name> # Stop (cascades to dependents)
zinit restart <name> # Restart a service
zinit kill <name> [signal] # Send signal to service
zinit logs <name> [-n N] # View service logs
zinit why <name> # Show why service is blocked
zinit tree # Show dependency tree
zinit reload # Reload configuration
zinit add-service <toml> # Add service at runtime
zinit remove-service <name> # Remove a service
zinit start-all # Start all user-class services
zinit stop-all # Stop all user-class services
zinit delete-all # Delete all user-class services
zinit shutdown # Stop all services, exit daemon
zinit poweroff # Power off system (signals init)
zinit reboot # Reboot system (signals init)
# Xinet socket activation proxy commands
zinit xinet set <name> # Create or update xinet proxy (replaces existing)
--listen <addr> # Listen address: host:port or unix:/path (repeatable)
--backend <addr> # Backend address: host:port or unix:/path
--service <name> # Zinit service to start on connection
[--connect-timeout <secs>] # Timeout for backend connect (default: 30)
[--idle-timeout <secs>] # Stop service after idle seconds (default: 0=never)
[--single-connection] # Allow only one connection at a time
zinit xinet delete <name> # Delete xinet proxy
zinit xinet list # List all xinet proxies
zinit xinet status [name] # Show proxy status (all if no name given)
# Debug commands
zinit debug-state # Full graph state dump
zinit debug-procs <name> # Process tree for a service
```
## Xinet Socket Activation Proxy
Xinet enables on-demand service startup through socket activation. When a client connects to the proxy's listening socket, the proxy starts the backend service and forwards traffic.
### Use Cases
- **Databases**: Start postgres on first query
- **Development Servers**: Start on HTTP request
- **Backup Services**: Start on trigger
- **Rarely-Used Services**: Reduce memory footprint
### Example: PostgreSQL with Socket Activation
Create the backend service:
```toml
# /etc/zinit/services/postgres.toml
[service]
name = "postgres"
exec = "/usr/bin/postgres -D /var/lib/postgres"
status = "stop" # Don't autostart
[lifecycle]
start_timeout_ms = 5000
stop_timeout_ms = 10000
```
Register the proxy (starts postgres on first connection):
```bash
zinit xinet set postgres-proxy \
--listen tcp:localhost:5432 \
--backend unix:/tmp/postgres.sock \
--service postgres \
--connect-timeout 10 \
--idle-timeout 300 # Stop after 5 minutes idle
```
Now clients connect to `localhost:5432` and postgres starts automatically.
### Example: Multiple Listen Addresses
```bash
zinit xinet set postgres-proxy \
--listen tcp:0.0.0.0:5432 \
--listen unix:/run/postgres.sock \
--backend unix:/tmp/postgres.sock \
--service postgres
```
### Proxy Features
- **Bidirectional Forwarding**: TCP ↔ TCP, Unix ↔ Unix, TCP ↔ Unix
- **Auto-Start Backend**: Starts service on first connection
- **Idle Timeout**: Automatically stops service after inactivity
- **Connection Limits**: Optional single-connection mode
- **Replace Mode**: `xinet set` replaces existing proxy (stops old one first)
- **Connection Stats**: Track active connections and total traffic
## Path Configuration
zinit uses platform-specific default paths:
### Linux (System/PID1 mode)
- Config directory: `/etc/zinit/services`
- System services: `/etc/zinit/system` (PID1 mode only)
- Socket: `/run/zinit.sock`
### macOS / Windows (Standalone mode)
- Config directory: `$HOME/hero/cfg/zinit`
- Socket: `$HOME/hero/var/zinit.sock`
You can override these with environment variables (see below).
See [docs/PATHS.md](docs/PATHS.md) for detailed path configuration documentation.
## Environment Variables
| `ZINIT_LOG_LEVEL` | `info` | Log level: `trace`, `debug`, `info`, `warn`, `error` |
| `ZINIT_CONFIG_DIR` | Platform-specific (see above) | Service config directory |
| `ZINIT_SOCKET` | Platform-specific (see above) | Unix socket path |
| `ZINIT_CONTAINER` | unset | If set, zinit-pid1 runs in container mode |
### Example: Custom Paths
```bash
# Use custom config and socket directories
export ZINIT_CONFIG_DIR=/opt/my-services
export ZINIT_SOCKET=/tmp/my-zinit.sock
# Start server
zinit-server
# Connect with CLI
zinit list
```
## Library Usage
zinit can be used as a library:
```rust
use zinit::{ZinitClient, ServiceConfig};
// Blocking client
let mut client = ZinitClient::connect_unix("/var/run/zinit.sock")?;
let services = client.list()?;
// Async client (requires "async" feature)
use zinit::AsyncZinitClient;
let mut client = AsyncZinitClient::connect_unix("/var/run/zinit.sock").await?;
let status = client.status("my-service").await?;
```
## Docker Usage
```bash
# Build test image
docker build -t zinit-test -f docker/Dockerfile .
# Run (uses container mode automatically)
docker run -it --rm zinit-test
# With debug logging
docker run -it --rm -e ZINIT_LOG_LEVEL=debug zinit-test
# Explicit container mode
docker run -it --rm -e ZINIT_CONTAINER=1 zinit-test
```
## Shutdown Ordering
Services are stopped in reverse dependency order:
```
Example: database <- app <- worker
Startup order: database -> app -> worker
Shutdown order: worker -> app -> database
```
When stopping a single service, dependents are stopped first:
- `zinit stop database` stops worker, then app, then database
- Dependencies are NOT auto-stopped (other services may need them)
## Development
```bash
cargo check --features full # Verify builds
cargo test --features full # Run tests
cargo build --release --features full # Build all binaries
cargo clippy --features full # Lint
# Run integration tests
cd tests/integration
./run.sh
```
## License
See LICENSE file.