Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.
Blackship
A FreeBSD jail orchestrator with TOML configuration, dependency management, state machine lifecycle control, and ZFS integration.
Features
- Declarative Configuration: Define jails in TOML with dependencies, networking, hooks, and resource limits
- Dependency Management: Real dependency-graph traversal for start/stop ordering; target jails by name, unambiguous prefix, tag, or ALL
- State Machine Lifecycle: Clean state transitions, devfs mounted per jail, /etc/rc boot and /etc/rc.shutdown on stop
- Hot Updates (EVA):
blackship evadiffs the config against running jails and applies parameter, rctl, and cpuset changes live via jail_set(JAIL_UPDATE) -- no restart, with drift warnings for changes that need one - VNET Networking: epair (if_bridge) and native netgraph (ng_bridge) backends, named networks with automatic host gateway wiring, deterministic MAC addresses
- Instant Provisioning: releases bootstrap into datasets with a @pristine snapshot; jail roots are zfs clones, created in under a second
- Jailfile Builds with Layer Cache: every RUN/COPY is snapshotted; rebuilds resume from the longest cached prefix like a Docker layer cache
- blackship commit: freeze a configured jail into a reusable release (zero-copy snapshot + clone + promote)
- pkgbase Bootstrap: FreeBSD 16+ userlands from fingerprint-verified base package repos (automatic; --pkgbase opts in earlier)
- Resource Limits: rctl (memory, pcpu, maxproc, openfiles, ...) plus cpuset pinning with least-loaded core allocation
- Health Checks & Supervision: HTTP, TCP, and command checks; warden auto-restart; optional dead-man ping to healthchecks.io/Uptime Kuma
- Migration & Import: zfs send | ssh zfs receive between hosts with the jail definition staged inside the dataset; import from iocage, ezjail, or plain rootfs archives
- Stats: per-jail CPU, RSS, and process counts from jls/ps libxo JSON
- Port Forwarding: PF-based port exposure with source IP binding
- Shell Completion: Bash, Zsh, and Fish completions
- Library API:
Host,Container,Execand friends drive ephemeral jails from your own program (a CI runner, say); the CLI is built on the same calls - MCP Server:
blackship mcpexposes host facts, the real parsers, and operator-approved file creation over MCP, so a model can author ablackship.tomlor Jailfile against this host instead of guessing
Requirements
- FreeBSD 15.0+ with jail support
- ZFS (optional, for snapshots/clones)
- PF (optional, for port forwarding)
Building from source also needs a C compiler and the base system headers:
the ioctl request codes and netgraph message constants are read out of
/usr/include at build time rather than hardcoded. Both ship with a
default FreeBSD install. The crate does not build on other operating
systems.
Installation
# Install from crates.io
# Or download precompiled binary from releases
# Install shell completion (optional)
Default Paths
Blackship uses XDG-compliant user directories by default:
| Path | Default | Environment Override |
|---|---|---|
data_dir |
~/.local/share/blackship |
XDG_DATA_HOME |
releases_dir |
~/.local/share/blackship/releases |
- |
cache_dir |
~/.cache/blackship |
XDG_CACHE_HOME |
These defaults allow running blackship without root for most operations. Override in blackship.toml for system-wide paths:
[]
= "/var/blackship"
= "/var/blackship/releases"
= "/var/blackship/cache"
Note: While paths are user-writable by default,
bootstrapextraction requires root privileges because FreeBSD base archives contain root-owned files with special permissions (setuid binaries, etc.). Blackship will re-exec through FreeBSD'smdowhen the current user has an applicablemac_dorule, then fall back todoasorsudo.
Quick Start
1. Initialize Jailfile
# Create a Jailfile in current directory
# Create with specific FreeBSD release
# TOML format instead of Dockerfile-like
2. Initialize Armada Configuration
Create blackship.toml:
[]
# Paths default to XDG directories (~/.local/share/blackship, ~/.cache/blackship)
# Uncomment to use system-wide paths:
# data_dir = "/var/blackship"
= true
= "zroot"
= "blackship"
[[]]
= "web"
= "15.1-RELEASE"
= "web.local"
[]
= true
= ["default"]
= "blackship0"
= "10.0.1.10"
= "10.0.1.1"
Or use blackship armada init to generate a template.
3. Bootstrap a Release
# Download and extract FreeBSD base (requires root for extraction).
# With ZFS enabled the release lands in its own dataset with a @pristine
# snapshot, so jails clone-provision from it instantly.
# FreeBSD 16 has no dist sets, so pkgbase is used automatically
# (16.0 is still -CURRENT; --pkgbase opts in on older branches)
# List available releases
4. Create Network
# if_bridge network with gateway on the bridge (requires root)
# netgraph network: ng_bridge plus a host-side gateway eiface, wired
# automatically; jails attached to it inherit the netgraph backend
Networks persist across reboots: blackship setup (run by the warden rc
script at boot) recreates missing bridges and gateway interfaces. If PF is
not running yet, blackship setup --enable-pf writes a minimal pf.conf with
the blackship anchors, sets pf_enable=YES, and starts it.
Named networks created this way can be referenced from blackship.toml with
[jails.network] networks = ["default"], and the same network can be used by
ephemeral jails with blackship run --network default.
5. Start Jails
# Start a specific jail
# Start all jails
# Dry run (show what would happen)
6. Interact with Jails
# Open console
# Execute command
# Check status
Using Blackship as a Library
Everything blackship run, cp, rm, bootstrap, build and commit
do is a library call first; the CLI is a thin coat of paint over it. A CI
runner (or anything else that wants throwaway jails) can depend on the crate
and skip the binary, the argument parser, the MCP server and the OTLP
exporter:
[]
= { = "0.2", = false }
use ;
use Duration;
let host = new.with_zfs;
// Whatever a crashed run left behind goes first.
host.reap_orphans?;
host.ensure_release?;
let job = host.create?;
let step = job.exec?;
println!;
job.copy_out?;
job.destroy?;
The rules of the road:
Hostis a description, not a connection: where releases, containers and state live, and which dataset backs them. Clone it freely; containers carry their own copy, so many can run on many threads with no shared mutable state.- Containers are ephemeral. Dropping a
Containerdestroys it. Callkeep()to let it outlive the handle (that is whatrun --detachdoes), anddestroy()when you want to see the errors a drop would swallow. execruns argv orsh -cwith a clean environment, a working directory, and a timeout or deadline. Output is captured, streamed to a callback, or inherited. A non-zero exit is data, not an error. On timeout every process in the container is killed from the host side (pkill -j), so nothing inside can dodge it.- Destroy is idempotent and works from any state: running, half-built,
or left behind by a
kill -9. It removes the jail, unmounts devfs and nullfs (refusing to delete anything while a mount is still live), releases the network lease, and destroys the clone. - Orphans are containers whose creating process is gone. Each one is
claimed with an ownership record before anything is built, so
orphans()/reap_orphans()find them by name prefix or label after a crash. Kept containers have no owner and are never reaped. - Releases and images:
releases(),has_release(),bootstrap()andensure_release()(FreeBSD 16 goes through fingerprint-verified pkgbase automatically).build()runs a Jailfile with the layer cache,commit_image()andContainer::commit()freeze a root into a new release, andremove_image()/remove_release()clean up. - Privilege: library calls assume they already run as root and return
Error::NeedsRoototherwise. Only the CLI re-executes through sudo/doas. - Errors are one typed
blackship::Errorenum. Noanyhowin sight.
examples/ephemeral.rs walks the whole lifecycle:
tests/containers_as_root.rs holds the end-to-end suite (timeouts, mounts,
orphan reaping, concurrency, build and commit); it runs only as root, against
a release you name:
Cargo features
| Feature | Default | What it brings |
|---|---|---|
cli |
yes | The blackship binary and its usage-rs parser; implies telemetry |
mcp |
yes | blackship mcp (mcp-host, schemars, tracing); implies cli |
telemetry |
via cli |
OTLP export through rama; without it [telemetry] still parses and does nothing |
inspect |
no | state machine introspection |
Machine-readable CLI
Automation can opt into a versioned JSON contract with the global
--format json option. The first contract version covers the read-only
commands most useful to management UIs:
Successful commands write an envelope to standard output:
Failures, including command-line parsing errors, exit non-zero and write a single JSON object to standard error. Error codes are stable identifiers intended for program logic; messages remain for people and diagnostics:
Commands without a complete JSON contract fail with
unsupported_output_format; they never fall back to mixed human-readable
output. Existing command-local flags such as blackship ps --json retain
their original, unenveloped output for compatibility.
Configuration Reference
Global Config
[]
# All paths are optional - defaults to XDG directories
= "~/.local/share/blackship" # Base data directory (default)
= "~/.local/share/blackship/releases" # FreeBSD releases (default)
= "~/.cache/blackship" # Download cache (default)
= "https://download.freebsd.org" # FreeBSD mirror
= true # Enable ZFS features
= "zroot" # ZFS pool name
= "blackship" # Base dataset name
= "https://hc-ping.com/…" # Dead-man ping from the supervisor (optional)
With ZFS enabled the jails dataset is mounted at data_dir/jails, so jail
roots live at the same paths whether or not they are datasets.
Jail Definition
[[]]
= "myapp" # Jail name (required)
= "15.1-RELEASE" # Base release (clone-provisioned when @pristine exists)
= "/jails/myapp" # Custom path (optional; default data_dir/jails/<name>)
= "myapp.local" # Hostname
= ["database"] # Dependencies
= ["web", "prod"] # Tags for group targeting (blackship down prod)
= 4 # devfs ruleset (default 4; 0 disables devfs)
= true # Run /etc/rc at start, /etc/rc.shutdown at stop (default)
= "service nginx stop" # Run inside the jail before teardown (overrides Jailfile STOP)
[]
= "1g" # rctl memoryuse:deny
= "150" # rctl pcpu:deny (percent)
= 200 # rctl maxproc:deny
= 2 # Pin to N least-loaded CPUs
# cpuset = "0,1" # Or pin to an explicit CPU list
[]
= true # Enable VNET
= ["default"] # Named networks to attach to
= "blackship0" # Optional if runtime network state defines a bridge
= "10.0.1.10" # Static IP, or omit for auto-assignment
= "10.0.1.1" # Optional if resolved from named network
= "02:00:00:00:00:01" # Static MAC (default: deterministic from jail name)
# backend = "netgraph" # Inherited from the named network when omitted
# shared = true # Share the host's network (ip4=inherit); ignored if vnet=true
[]
= ["8.8.8.8", "8.8.4.4"] # DNS servers
= "custom" # custom or inherit
[]
= true
[[]]
= "http"
= "curl -sf http://localhost:80/health"
= "jail"
= 30
= 10
= 3
[[]]
= "process"
= "pgrep nginx"
= "jail"
[[]]
= "post_start" # pre_create, post_create, pre_start, post_start,
= "jail" # pre_stop, post_stop, pre_eva, post_eva
= "/etc/rc.d/nginx start"
= "abort" # abort or continue
[[]]
= "pre_stop"
= "jail"
= "/etc/rc.d/nginx stop"
= "continue"
Commands
Lifecycle
| Command | Description |
|---|---|
blackship up [target] [--all] [--dry-run] |
Start jail(s) with dependencies |
blackship down [target] [--all] [--dry-run] |
Stop jail(s) in reverse order |
blackship restart [target] [--all] [--dry-run] |
Restart jail(s) |
blackship eva [target] [--all] [--dry-run] |
Hot-update running jail(s) to match the config, no restart |
Targets accept a jail name, an unambiguous prefix, a tag (from tags = [...]
in the jail definition), or ALL.
eva recomputes each jail's parameters from the config, diffs them against
the live values from jls, and applies only the changes in one
jail_set(JAIL_UPDATE) call, then replaces rctl rules and re-pins the cpuset.
path, vnet, and IP addresses cannot change live: drift on those is
reported as a restart-required warning and skipped. Not-running jails are
skipped. --dry-run prints the diff without touching anything.
| blackship ps [--json] | List jail status |
| blackship check | Validate configuration |
| blackship setup [--enable-pf] | Reapply networks and PF anchors; --enable-pf turns PF on |
| blackship cleanup <jail> [--force] | Clean up failed jail resources |
| blackship init [-f file] [--release] [--toml] | Create a new Jailfile |
Console & Execution
| Command | Description |
|---|---|
blackship console <jail> [-u user] |
Open interactive shell |
blackship exec <jail> [-u user] [-w dir] [-e K=V] [--clear-env] -- <cmd> |
Execute command in jail (--clear-env starts from an empty environment, keeping only -e values) |
blackship run --name <n> --release <r> [--network <net>] [-d] -- <cmd> |
Run ephemeral jail (auto-cleanup unless -d) |
File Operations
| Command | Description |
|---|---|
blackship cp <src> <dest> |
Copy files (use jail:path for jail paths) |
blackship rm <jails...> [-f] [--volumes] |
Remove/destroy jails |
Bootstrap & Releases
| Command | Description |
|---|---|
blackship bootstrap <release> [-f] [-a archives] [--pkgbase] |
Download FreeBSD release (pkgbase automatic for 16+) |
blackship releases [list|delete|verify] [--json] |
Manage releases |
Networking
| Command | Description |
|---|---|
blackship network create <name> -s <subnet> [-g gw] [-b bridge] [--backend epair|netgraph] |
Create network (requires root) |
blackship network destroy <name> [--force] |
Destroy network (requires root) |
blackship network list |
List Blackship-managed networks |
blackship expose <jail> -p <port> [-I bind-ip] [--proto tcp|udp] |
Expose port |
blackship ports [jail] |
List exposed ports |
Snapshots & Clones (requires ZFS)
| Command | Description |
|---|---|
blackship snapshot create <jail> [name] |
Create snapshot |
blackship snapshot list <jail> [--json] |
List snapshots |
blackship snapshot rollback <jail> <snap> [--force] |
Rollback to snapshot |
blackship snapshot delete <jail> <snap> |
Delete snapshot |
blackship clone <jail>@<snap> <newname> |
Clone from snapshot |
blackship commit <jail> <release> |
Freeze a jail into a reusable release (zero-copy) |
Snapshots (and commits) stage the jail definition at .blackship/ inside
the dataset, so zfs send carries everything needed to rebuild the jail.
Export & Import
| Command | Description |
|---|---|
blackship export <jail> [-o file] [--zfs-send] |
Export to archive |
blackship import <file> [-n name] [--force] |
Import from archive |
blackship import <file> --from iocage|ezjail|rootfs|auto [-n name] |
Import from another jail manager |
blackship migrate <jail> user@host [--remote-dataset ds] |
Move a jail to another host over ssh |
Build System
| Command | Description |
|---|---|
blackship build [-f Jailfile] [-n name] [--build-arg K=V] [--dry-run] |
Build from Jailfile (ZFS layer cache: unchanged steps print CACHED) |
blackship template list |
List templates |
blackship template inspect <file> |
Show Jailfile details |
blackship template validate <file> |
Validate Jailfile |
Health & Monitoring
| Command | Description |
|---|---|
blackship health [jail] [-w] [-i interval] [--json] |
Health check status |
blackship stats [jail] [--json] |
Per-jail CPU, RSS, and process counts |
blackship supervise |
Start Warden supervisor for auto-restart |
blackship logs <jail> [-f] [-n lines] |
Tail jail logs |
blackship audit <jail> [--json] |
Durable lifecycle history, peak usage, exit reason |
blackship qos <jail> [--show|--steady|--startup] |
Inspect or switch the QoS profile |
blackship gc [jail] [--dry-run] [--force] [--json] |
Reclaim orphaned jail resources |
Armada (Multi-Jail Orchestration)
| Command | Description |
|---|---|
blackship armada init [-f file] |
Create a new blackship.toml |
blackship armada up [-d] [jails...] |
Start all jails |
blackship armada down [jails...] |
Stop all jails |
blackship armada build [jails...] |
Build jails from Jailfiles |
blackship armada ps [--json] |
Show status of all jails |
blackship armada config [--show] |
Validate and show configuration |
Config File Merging
Armada supports merging multiple config files (later files override earlier):
# Merge base config with production overrides
# Merge multiple files
Jailfile References
Jails in blackship.toml can reference Jailfiles for building:
[[]]
= "web"
= "./web" # Directory containing Jailfile
= ["db"]
[[]]
= "api"
= "./custom/Api.jailfile" # Explicit Jailfile path
Shell Completion
| Command | Description |
|---|---|
blackship completion bash|zsh|fish |
Generate shell completion |
MCP Server
| Command | Description |
|---|---|
blackship mcp |
Serve the MCP protocol on stdin/stdout (see MCP Server) |
Jailfile Format
Jailfiles define reproducible jail builds, similar to Dockerfiles:
# Jailfile
FROM 15.1-RELEASE
# Labels (metadata)
LABEL name=nginx-jail version=1.0
# Build arguments
ARG NGINX_VERSION=1.24
# Environment variables
ENV NGINX_VERSION=${NGINX_VERSION}
# Run commands (executed via jexec)
RUN pkg install -y nginx-${NGINX_VERSION}
RUN sysrc nginx_enable=YES
# Copy files from build context
COPY nginx.conf /usr/local/etc/nginx/nginx.conf
COPY html/ /usr/local/www/html/
# Set working directory
WORKDIR /usr/local/www
# Expose ports (documentation)
EXPOSE 80/tcp
EXPOSE 443/tcp
# Default command
CMD /usr/local/sbin/nginx -g 'daemon off;'
# Run inside the jail before teardown
STOP /usr/local/sbin/nginx -s quit
STOP runs before /etc/rc.shutdown when the jail is stopped. A stop = key on
the jail in blackship.toml overrides it.
TOML Format (Alternative)
# Jailfile.toml
[]
= "nginx-jail"
= "1.0"
= "15.1-RELEASE"
[[]]
= "NGINX_VERSION"
= "1.24"
[[]]
= "run"
= "pkg install -y nginx"
[[]]
= "copy"
= "nginx.conf"
= "/usr/local/etc/nginx/nginx.conf"
[[]]
= 80
= "tcp"
= "/usr/local/sbin/nginx -g 'daemon off;'"
[]
= "/usr/local/sbin/nginx -s quit"
Build Commands
# Basic build
# With build arguments
# Dry run
ZFS Integration
ZFS is what makes jails cheap. With zfs_enabled = true:
- Releases bootstrap into their own dataset and get a
@pristinesnapshot - Jail roots are
zfs clones of that snapshot, so creation is near-instant and jails share the base blocks instead of copying them - Jailfile builds snapshot each step, giving rebuilds a layer cache
blackship commitfreezes a jail back into a reusable release- Snapshots carry the jail's own definition, and send/receive moves jails between hosts
The jails dataset is mounted at data_dir/jails, so a jail root is at the
same path whether or not it is a dataset. Without ZFS everything still works,
but each jail is a full copy of the release (Blackship refuses the copy if the
filesystem cannot take it).
Instant provisioning and commit
# Bootstrap once: extracts to a dataset, snapshots it @pristine
# Jails clone from it: sub-second, and nearly free on disk
# Configure a jail, then freeze it into a reusable release
# Everything cloned from it starts pre-configured
Build layer cache
Every RUN and COPY is snapshotted as bs-layer-<n>-<hash>, keyed by a
rolling hash of the instructions before it, the build arguments, the base
release, and the contents of anything copied in. A rebuild rolls back to the
longest cached prefix and continues from there:
$ blackship build -f runner/Jailfile -n runner
CACHED steps 1-5 (layer bs-layer-4-a1aadc5d826c)
Build complete! Jail root: /var/blackship/jails/armada-runner
Change a line in the Jailfile and only that step and everything after it re-runs, exactly like a Docker layer cache.
Snapshot Workflow
Snapshots stage the jail's definition (and its Jailfile, when known) at
.blackship/ inside the dataset first, so a zfs send of the snapshot
carries everything needed to rebuild the jail elsewhere.
# Create snapshot before changes
# Make changes
# If something breaks, rollback
# Clone for testing
Export/Import with ZFS
# Fast export using ZFS send
# Standard tar.zst export
# Import (auto-detects format)
# Import from another jail manager
# Move a stopped jail to another host over ssh
Networking
Every VNET jail gets its own network stack and one interface plugged into a host bridge. Blackship implements that two ways, and a named network picks which one:
epair (default) |
netgraph |
|
|---|---|---|
| Host bridge | if_bridge |
ng_bridge node |
| Jail interface | if_epair pair (epair0a/epair0b) |
ng_eiface (ngethN) |
| Gateway lives on | the bridge interface | a host-side ng_eiface |
| VLAN tagging | supported | not supported |
Named networks
A named network is a persisted record (subnet, gateway, bridge, backend), not
a live interface. Creating one realizes it on the host; blackship setup
re-realizes it after a reboot, when bridges and eifaces are gone but the
record remains:
Created network 'default' on bridge 'ngbridge0' (netgraph)
Subnet: 10.0.1.0/24
Gateway: 10.0.1.1
Host gateway interface: ngeth0
Jails attach by name and inherit the backend, so nothing in the jail definition needs to know which dataplane is in use:
[]
= true
= ["default"]
= "10.0.1.10"
How the netgraph backend is wired
ng_bridge is a kernel graph node with numbered linkN hooks. Blackship
hangs one ng_eiface off a hook per jail, plus one for the host itself,
which is where the gateway address lives:
ng_bridge (ngbridge0)
├── link0 ── ng_eiface ngeth0 [host] 10.0.1.1
├── link1 ── ng_eiface ngeth1 [jail web] 10.0.1.10
└── link2 ── ng_eiface ngeth2 [jail db] 10.0.1.11
host NIC (em0) ── PF NAT ── routing ── ngeth0
There is no epair pair and no if_bridge: the jail interface is moved into
the jail's vnet with SIOCSIFVNET, and traffic reaches the outside through
normal host routing plus a NAT rule. Outbound therefore needs
net.inet.ip.forwarding=1 (Blackship sets it when it realizes a gateway) and
a NAT rule for the subnet in pf.conf:
nat on $ext_if inet from 10.0.1.0/24 to any -> ($ext_if)
Concurrent jail creation is safe: two creators racing for the same free
linkN retry the next index, and IP claims are arbitrated by the lease store
under a lock rather than by whoever wrote last.
Interface ownership
Host-side interfaces are tagged into the blackship interface group
(ifconfig -g blackship lists them). Cleanup checks that tag before
destroying an interface it found by name, so a recycled name belonging to
something else is never torn down. Only the host end is tagged, because
moving an interface into a vnet strips its groups.
Jail interfaces also get a deterministic MAC by default: the FreeBSD OUI
58:9c:fc plus a hash of the jail name and bridge, so an address survives
restarts and differs between clones. Set mac_address to override.
Gotcha: one namespace, two bridge types
Loading ng_ether gives every ethernet interface a netgraph node named after
itself, and that includes if_bridge interfaces. A named network created
with the epair backend on blackship0 therefore occupies the name
blackship0 in the netgraph namespace too, and a netgraph bridge cannot then
use it:
Error: Network error: NgNameNode(.:bridge_tmp, blackship0) failed: Address already in use
Give the two backends distinct bridge names (blackship0 and ngbridge0).
Port Forwardingemains the default and is what most setups want.
Port Forwarding
Uses PF anchors to avoid modifying /etc/pf.conf:
# Expose nginx on port 80
# Expose on specific host IP
# Different internal port
Add to /etc/pf.conf:
rdr-anchor "blackship"
anchor "blackship"
Port forwards are persisted under Blackship's data directory. After a PF
restart or host reboot, run blackship setup to recreate the anchor and
reapply the saved rules.
Health Checks
All health checks are command-based (exit 0 = healthy).
HTTP Check
[[]]
= "api"
= "curl -sf http://localhost:8080/health"
= "jail"
= 30
= 10
TCP Check
[[]]
= "postgres"
= "nc -z localhost 5432"
= "jail"
Command Check
[[]]
= "nginx-running"
= "service nginx status"
= "jail"
Monitoring
# One-time check
# Watch mode (updates every 5 seconds)
# JSON output for scripting
Lifecycle state, reclamation, and telemetry
Every host mutation up performs is checkpointed to a scope record at
<data_dir>/scope/<jail>.toml before it happens, and every transition is
appended to <data_dir>/audit/<jail>.jsonl. The scope record is the reclamation
work-list; the audit log outlives it.
Reclaiming orphans
A jail killed out of band (jail -r, a panic, a hard reset) leaves its epair,
rctl rules, lease, mounts, and dataset behind. gc finds them by diffing scope
records against what is actually running:
Datasets blackship did not create, and jails marked ephemeral = false, are
reported but never destroyed without --force. up and supervise run the
report-and-reap-orphans half automatically.
Two-phase QoS
A jail usually needs headroom while it warms caches and forks workers, and a
tighter cap once it settles. [jails.qos] gives it both:
[]
= "healthy" # "healthy" | "timer" | "manual"
= 120
[]
= "4g"
= "400"
[]
= "2g"
= "200"
The healthy transition fires on the first passing healthcheck and therefore
needs blackship supervise; max_startup_secs is its fallback deadline. For
one-shot blackship up there is no warden, so shift by hand:
Only the resources a profile names are swapped — custom rules entries survive
the shift, and eva reconciles against the recorded phase rather than
reverting it.
Draining and cascade policy
[jails.drain] blocks new TCP connections through a per-jail PF sub-anchor
(blackship/drain/<jail>) and waits for established states to close before
teardown, up to timeout_secs. cascade decides what happens to dependents on
down: strict stops them (default), detach stops only the target, isolate
leaves them running but fences them off at the firewall.
Post-mortem
This reads the durable JSONL, so it still answers after the jail, its scope
record, and a reboot are gone — including peak racct usage sampled by the
supervisor and the recorded termination reason. Peaks are bounded by
usage_sample_secs (default 30s); they are sampled maxima, not exact kernel
counters.
OTLP export
Adding a [telemetry] block sends the same event stream to a collector over
OTLP/HTTP, alongside racct gauges:
[]
= "http://127.0.0.1:4318"
= "blackship"
= 30
[]
= "Bearer <token>"
Omitting the table costs nothing: no exporter is built, no runtime is started, no socket is opened. A collector that is down, slow, or misconfigured warns once and never fails a jail operation.
Dependencies
Jails start in dependency order and stop in reverse:
[[]]
= "app"
= ["cache", "database"]
[[]]
= "cache"
[[]]
= "database"
# Starts: database → cache → app
# Stops: app → cache → database
Examples
Web Application Stack
[]
# data_dir defaults to ~/.local/share/blackship
= true
= "zroot"
= "blackship"
[[]]
= "postgres"
= "15.1-RELEASE"
= "db.local"
[]
= true
= "blackship0"
= "10.0.1.10"
= "10.0.1.1"
[[]]
= "redis"
= "15.1-RELEASE"
= "cache.local"
[]
= true
= "blackship0"
= "10.0.1.11"
= "10.0.1.1"
[[]]
= "webapp"
= "15.1-RELEASE"
= "app.local"
= ["postgres", "redis"]
[]
= true
= "blackship0"
= "10.0.1.20"
= "10.0.1.1"
[]
= ["8.8.8.8"]
= "custom"
[]
= true
[[]]
= "http"
= "curl -sf http://localhost:3000/health"
= "jail"
= 30
Backup and Migration
# Create snapshot
# Export for migration
# On new host
# Edit blackship.toml to add jail config
CI/CD Integration (Example)
This is an example of how Blackship could be used as a backend for CI/CD systems. This is not a built-in integration - it demonstrates how the run, exec, cp, and rm commands can be combined for CI/CD workflows.
Example: Gitea Actions with act_runner
Blackship could be used as a backend for Gitea Actions via act_runner.
Setup
- Bootstrap a release:
- Configure act_runner with jail labels:
runner:
labels:
- "freebsd-15:jail://15.1-RELEASE"
- Workflows targeting
runs-on: freebsd-15would execute in ephemeral jails.
How it Would Work
When act_runner receives a job with a jail:// label, the runner could:
- Create an ephemeral jail via
blackship run --name gitea-runner-<id> --release <release> --detach - Clone the repository into the jail using
blackship cp - Execute each step via
blackship exec <jail> --workdir /workspace -- <command> - Clean up via
blackship rm <jail> --force
Note: This requires custom act_runner configuration or a wrapper script - it is not built into act_runner by default.
MCP Server
blackship mcp speaks the Model Context Protocol
over stdin/stdout, so an MCP-capable assistant can author jail configuration
for this host. Writing a blackship.toml or a Jailfile by hand means knowing
two schemas and knowing what the host can actually do; the server supplies both,
plus the real parsers, so a draft is checked before it reaches disk.
It is built by default. Compile without it using --no-default-features.
Running it
It needs no root, and it does not require a blackship.toml to exist --
creating one is the point. Register it with a client:
Pass --config <path> before mcp to change the manifest path the tools
default to. Stdout carries the JSON-RPC frame stream, so diagnostics go to
$XDG_DATA_HOME/blackship/mcp.log (by default
~/.local/share/blackship/mcp.log) instead; set RUST_LOG to raise the level.
Tools
Read-only, no approval needed:
| Tool | Returns |
|---|---|
host_facts |
Kernel version and the real feature gates, rctl state and managed resources, CPU count, zpools, bootstrapped releases, running jails |
manifest_inspect |
The parsed manifest as JSON |
manifest_validate |
Every diagnostic, staged read -> parse -> validate |
jailfile_inspect |
The parsed Jailfile as JSON |
jailfile_validate |
Every bad line with line and column, in one call |
File-producing, and approval is not optional:
| Tool | Writes |
|---|---|
manifest_create |
A blackship.toml rendered from a project name and a list of jails |
jailfile_create |
A Jailfile in the TOML format |
host_facts is what makes the rest worth having: releases, interfaces, and
resource limits come from the host rather than from a model's weights.
Writes are gated on the operator
Neither creating tool can write a file on its own authority. Both render the
text, validate it through the same code blackship up and blackship build
use, and then ask you through an MCP
elicitation.
Nothing lands on disk unless you set confirm, and replacing an existing file
additionally needs overwrite, which is only ever offered when the file really
exists. The prompt names the absolute path.
The gate fails closed. A declined or cancelled request, a form returned without
confirm, a client that does not support elicitation, a prompt left unanswered
for two minutes, a target directory that does not exist, and a draft that does
not validate all produce the same result on disk: nothing. A refusal comes back
as a payload with "written": false and a reason, so the model can tell a
rejection from an error.
Writes themselves go through a temp file in the target directory followed by a rename, so an interrupted write cannot truncate an existing manifest. That is also why the target's directory has to exist: it is checked before you are asked, so an approval is never spent on a write that cannot land. blackship does not create directories on your behalf.
Prompts
The prompts carry the workflow -- they tell the model which tools to call and in what order, rather than leaving it to infer that.
| Prompt | Purpose |
|---|---|
new_project |
Author a blackship.toml: gather host facts, draft, validate, then create |
new_jailfile |
The same arc, ending at jailfile_create |
diagnose_config |
Explain why an existing file is rejected, in terms of the schema |
Resources
| URI | Contents |
|---|---|
blackship:///man |
The CLI manual, generated from the live command spec |
blackship:///man.kdl |
The full command tree as KDL |
blackship:///schema/manifest |
JSON Schema for what manifest_create accepts |
blackship:///schema/jailfile |
JSON Schema for what jailfile_create accepts |
blackship:///reference/jailfile |
The line-format keywords, including which Dockerfile constructs do not exist here |
blackship:///reference/jail-params |
The reserved jail_set(2) parameters blackship manages itself |
The manual and the schemas are generated, not hand-written, so a new subcommand or a new parameter shows up the day it is added and cannot drift out of date.
Troubleshooting
Jail won't start
# Check configuration
# Try dry run
# Clean up failed resources
Network issues
# List Blackship-managed networks
# Check jail IP
# Verify routing
ZFS issues
# Verify dataset exists
|
# Check snapshots
# Manual cleanup
blackship up aborts where it used to warn
Resource-limit and VNET-attach failures are fatal: the jail is removed and
its resources are rolled back rather than left running in a half-configured
state. A jail with [jails.resources] set will now fail on a host without
RCTL instead of quietly ignoring its limits.
kern.racct.enable is a read-only tunable, so it cannot be set at runtime.
Add it to /boot/loader.conf and reboot:
kern.racct.enable="1"
Rejected params entries
Manifest params cannot override the keys Blackship uses to establish jail
identity and isolation — vnet, path, name, securelevel,
devfs_ruleset, enforce_statfs, allow.* and similar. Those are reported
and ignored rather than applied. Set the supported options ([jails.network],
[jails.resources]) instead.
ping fails inside blackship run
Ephemeral run jails are not granted allow.raw_sockets, allow.socket_af
or allow.chflags. Use a managed jail defined in the manifest for workloads
that need raw sockets or chflags.
License
BSD-3-Clause - See LICENSE file for details.
Author
Abdelkader Boudih oss@seuros.com