blackship 0.6.2

A FreeBSD jail manager with state machine control
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
# Blackship

A FreeBSD jail orchestrator with TOML configuration, dependency management, state machine lifecycle control, and ZFS integration.

## Documentation

- [Blackship Technical Manual (PDF, latest release)]https://github.com/seuros/blackship/releases/latest/download/blackship-manual.pdf

The README is the quick reference. The manual is built for every release and
attached to it: the complete operator guide, architecture, configuration,
command reference, integration, security model, and troubleshooting material.

## 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 eva` diffs 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`, `Exec` and friends drive ephemeral jails from your own program (a CI runner, say); the CLI is built on the same calls
- **MCP Server**: `blackship mcp` (stdio, or Streamable HTTP with a bearer token) exposes host facts, the real parsers, and operator-approved file creation over MCP, so a model can author a `blackship.toml` or 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

```sh
# Install from crates.io
cargo install blackship

# Or download precompiled binary from releases
fetch https://github.com/seuros/blackship/releases/latest/download/blackship-freebsd-amd64.tar.gz
tar xzf blackship-freebsd-amd64.tar.gz
sudo mv blackship /usr/local/bin/

# Install shell completion (optional)
blackship completion bash > /usr/local/etc/bash_completion.d/blackship
blackship completion zsh > /usr/local/share/zsh/site-functions/_blackship
blackship completion fish > ~/.config/fish/completions/blackship.fish
```

## 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:

```toml
[config]
data_dir = "/var/blackship"
releases_dir = "/var/blackship/releases"
cache_dir = "/var/blackship/cache"
```

> **Note:** While paths are user-writable by default, `bootstrap` extraction requires root privileges because FreeBSD base archives contain root-owned files with special permissions (setuid binaries, etc.). Blackship will re-exec through FreeBSD's `mdo` when the current user has an applicable `mac_do` rule, then fall back to `doas` or `sudo`.

Automatic privilege escalation can be controlled globally:

```sh
# Fail instead of re-executing through mdo, doas, or sudo
blackship --no-escalate up --all

# Allow escalation, but never prompt for authentication
blackship --non-interactive up --all
```

`--non-interactive` passes `-n` to `doas` and `sudo`. FreeBSD's `mdo` is
already non-interactive: authorization comes entirely from `mac_do`, without a
password prompt. `--no-escalate` takes precedence when both options are used.

## Quick Start

### 1. Initialize Jailfile

```sh
# Create a Jailfile in current directory
blackship init

# Create with specific FreeBSD release
blackship init --release 15.1-RELEASE

# TOML format instead of Dockerfile-like
blackship init --toml
```

### 2. Initialize Armada Configuration

Create `blackship.toml`:

```toml
[config]
# Paths default to XDG directories (~/.local/share/blackship, ~/.cache/blackship)
# Uncomment to use system-wide paths:
# data_dir = "/var/blackship"
zfs_enabled = true
zpool = "zroot"
dataset = "blackship"

[[jails]]
name = "web"
release = "15.1-RELEASE"
hostname = "web.local"

[jails.network]
vnet = true
networks = ["default"]
bridge = "blackship0"
ip = "10.0.1.10"
gateway = "10.0.1.1"
```

Or use `blackship armada init` to generate a template.

### 3. Bootstrap a Release

```sh
# 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.
blackship bootstrap 15.1-RELEASE

# FreeBSD 16 has no dist sets, so pkgbase is used automatically
# (16.0 is still -CURRENT; --pkgbase opts in on older branches)
blackship bootstrap 16.0-CURRENT

# List available releases
blackship releases
```

### 4. Create Network

```sh
# if_bridge network with gateway on the bridge (requires root)
blackship network create default --subnet 10.0.1.0/24 --gateway 10.0.1.1 --bridge blackship0

# netgraph network: ng_bridge plus a host-side gateway eiface, wired
# automatically; jails attached to it inherit the netgraph backend
blackship network create default --subnet 10.0.1.0/24 --backend netgraph --bridge ngbridge0
```

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. Jails reach
beyond the host only through a NAT rule you add; see
[Outbound traffic](#outbound-traffic).

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`. Those get the
host's `/etc/resolv.conf`, minus nameservers on the host's loopback that a
VNET stack cannot reach; when that leaves nothing (a host on
`local_unbound`), `run` refuses and asks for `--dns <ip>`.

### 5. Start Jails

```sh
# Start a specific jail
blackship up web

# Start all jails
blackship up --all

# Dry run (show what would happen)
blackship up --all --dry-run
```

### 6. Interact with Jails

```sh
# Open console
blackship console web

# Execute command
blackship exec web -- pkg install -y nginx

# Check status
blackship ps
blackship ps --json
```

## 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:

```toml
[dependencies]
blackship = { version = "0.3", default-features = false }
```

```rust
use blackship::{ContainerSpec, Exec, Host, Limits, Mount, Network, Selector};
use std::time::Duration;

let host = Host::new("/var/db/kim/blackship").with_zfs("zroot", "kim/blackship");

// Whatever a crashed run left behind goes first.
host.reap_orphans(&Selector::prefix("kim-"))?;
host.ensure_release("16.0-CURRENT")?;

let job = host.create(
    &ContainerSpec::new("kim-42", "16.0-CURRENT")
        .hostname("ci")
        .network(Network::Inherit)
        .limits(Limits::new().memory("4g").max_processes(512))
        .mount(Mount::read_only("/var/cache/kim/src/42", "/work"))
        .label("job", "42"),
)?;

let step = job.exec(
    Exec::shell("make test")
        .cwd("/work")
        .env("CI", "true")
        .timeout(Duration::from_secs(900))
        .on_output(|stream, bytes| print!("{stream:?}: {}", String::from_utf8_lossy(bytes))),
)?;
println!("exit: {:?}", step.exit);

job.copy_out("/work/report.xml", "/tmp/kim-42.xml")?;
job.destroy()?;
```

The rules of the road:

- **`Host`** is 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 `Container` destroys it. Call
  `keep()` to let it outlive the handle (that is what `run --detach` does),
  `hand_over(pid)` to give it to another process (a root helper creating
  containers for a daemon), and `destroy()` when you want to see the errors
  a drop would swallow.
- **Networking:** `Network::None` (the default), `Inherit` (the host's
  stack and resolver) or `Vnet(name)` (a leased address on a Blackship
  network and the host's resolver, minus loopback nameservers it cannot
  reach). `nameserver(ip)` overrides the resolver either way.
- **Mounts** are nullfs. `read_write` mounts are `nosuid` unless you call
  `allow_setuid()`; `noexec()` and `nosuid()` apply to either kind. These
  flags cover the jail-side mount only: the host path is as setuid-capable
  as its own filesystem, so keep host directories that jobs write to on a
  `setuid=off` dataset when other users can reach them.
- **`exec`** runs argv or `sh -c` with 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. A handed-over container is an orphan once its new owner is gone.
  Kept containers have no owner and are never reaped.
- **Releases and images:** `releases()`, `has_release()`, `bootstrap()` and
  `ensure_release()` (FreeBSD 16 goes through fingerprint-verified pkgbase
  automatically). `build()` runs a Jailfile with the layer cache,
  `commit_image()` and `Container::commit()` freeze a root into a new
  release, and `remove_image()` / `remove_release()` clean up. Baking an
  image by installing base packages in a container needs
  `ContainerSpec::allow_chflags()`: pkgbase sets file flags.
- **Privilege:** library calls assume they already run as root and return
  `Error::NeedsRoot` otherwise. Only the CLI re-executes through `mdo`, `doas`,
  or `sudo`; callers can disable that with `--no-escalate` or prevent prompts
  with `--non-interactive`.
- **Errors** are one typed `blackship::Error` enum. No `anyhow` in sight.

`examples/ephemeral.rs` walks the whole lifecycle:

```sh
sudo cargo run --no-default-features --example ephemeral -- \
    --data-dir /var/db/blackship --zfs zroot/blackship --release 16.0-CURRENT
```

`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:

```sh
sudo env BLACKSHIP_E2E_DATA_DIR=/var/tmp/bw BLACKSHIP_E2E_ZFS=zroot/blackship-e2e \
    BLACKSHIP_E2E_RELEASE=16.0-CURRENT \
    cargo test --test containers_as_root -- --ignored --test-threads=1
```

### 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 |
| `ui` | no | `blackship ui`, a placeholder web page served by rama (see [Web UI]#web-ui-placeholder); implies `cli` |
| `inspect` | no | state machine introspection |

## Machine-readable CLI

Automation can opt into a versioned JSON contract with the global
`--format json` option. As an inherited global, it works before or after the
selected command (`blackship --format json capabilities` and
`blackship capabilities --format json` are equivalent). The first contract
version covers the read-only commands most useful to management UIs:

```sh
blackship --format json ps
blackship --format json ps --host
blackship --format json check
blackship --format json capabilities
blackship --format json host
blackship --format json network list
blackship --format json ports
blackship --format json ports web
blackship --format json releases list
blackship --format json stats
blackship --format json stats web
blackship --format json health
blackship --format json health web
blackship --format json audit web
blackship --format json snapshot list web
blackship --format json armada ps
blackship --format json up web --dry-run
blackship --format json down web --dry-run
blackship --format json restart web --dry-run
blackship --format json eva web --dry-run
```

Successful commands write an envelope to standard output:

```json
{
  "schema_version": 1,
  "ok": true,
  "data": []
}
```

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:

```json
{
  "schema_version": 1,
  "ok": false,
  "error": {
    "code": "jail_not_found",
    "message": "Jail 'web' not found"
  }
}
```

Commands without a complete JSON contract fail with
`unsupported_output_format`; they never fall back to mixed human-readable
output. Streaming modes such as `health --watch` are intentionally excluded
from the single-envelope contract. Existing command-local flags such as
`blackship ps --json` retain their original, unenveloped output for
compatibility.

`blackship capabilities` requires neither a manifest nor root access. Its JSON
report lets clients discover the Blackship version, output schema, compiled
features, FreeBSD kernel capabilities, host facilities, and installed privilege
escalators before enabling UI actions. The `cli.machine_output` array lists
each exact command mode that supports the global JSON contract, using a stable
`operation` identifier plus its privilege and mutation behavior. Clients should
check for the operation instead of inferring support from the Blackship version:

```sh
blackship --format json capabilities \
  | jq '.data.cli.machine_output[] | select(.operation == "armada.ps")'
```

A new command mode with a JSON contract must register an operation id in
`OPERATION_SPECS` (`src/commands/capabilities.rs`) and in the test's candidate
table; a test fails when a JSON-capable mode has no row or a row has no JSON mode.
Only the `--dry-run` forms of `up`, `down`, `restart`, `eva` and `autostart` have
a JSON contract, so only those appear.

`blackship host` returns the same best-effort planning profile as the
`blackship:///host` MCP resource: kernel and facility capabilities, CPU and
memory capacity and claims, ZFS pools, releases, networks and available
addresses, PF state, manifest jails, and unmanaged running jails. Probes that
cannot run unprivileged report null or a local error instead of failing the
whole profile.

`blackship ps --host` adds running jails outside the selected manifest to the
configured Blackship inventory. Its result identifies each row's manager and
ownership, includes the selected project, the first config path
(`config_path`) and every merged path (`config_paths`), and includes a
passive, last-known health summary. `ps --host` never executes health checks or
recovery actions: `health` and `supervise` atomically refresh the summary under
`<data_dir>/health`. The summary reports why a result is unknown (for example,
`stopped`, `not_checked`, `stale_jid`, or `unmanaged`) and includes its
`checked_at` timestamp so clients can judge freshness. A cycle that was shed by
`health_concurrency` or that errored never refreshes the timestamp, and
`supervise --autostart` monitors only the autostart jails, so the others report
`not_checked`. The counts are the last result of each check, not the verdict,
and nothing expires them: judge freshness by `checked_at` (a paced or slow
supervisor can leave it older than the check interval). A restarted jail reads
`stale_jid` until the supervisor's checker, which follows the new JID, reports
again. Snapshots are deleted on stop, `rm`, `cleanup` and `gc`, and a one-shot
`health` inside the start period does not replace a settled result. Stopped unmanaged jails
cannot be discovered without a known manifest and are therefore not reported.

Lifecycle commands support the global JSON format in dry-run mode. Their
`data` object contains the requested operation and its ordered steps, allowing
management tools to preview dependency-aware changes without parsing terminal
text or modifying the host. Live lifecycle operations remain text-only.

## Configuration Reference

### Global Config

```toml
[config]
project = "orbital"                        # Jail name prefix (default: the config file's directory name)
# All paths are optional - defaults to XDG directories
data_dir = "~/.local/share/blackship"      # Base data directory (default)
releases_dir = "~/.local/share/blackship/releases"  # FreeBSD releases (default)
cache_dir = "~/.cache/blackship"           # Download cache (default)
mirror_url = "https://download.freebsd.org"  # FreeBSD mirror
zfs_enabled = true                         # Enable ZFS features
zpool = "zroot"                            # ZFS pool name
dataset = "blackship"                      # Base dataset name
monitor_ping_url = "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. Blackship sets
that mountpoint only when it creates the dataset; every jail dataset carries
its own mountpoint, so a run with a different `data_dir` no longer drags the
shared parent along with it.

Running jails are named `<project>-<name>`: jail `web` in project `orbital`
runs as `orbital-web`, which is what `jls` and `ps` show. Commands take
either form. Without `project`, the name comes from the directory holding
`blackship.toml`, however you spell its path.

### Jail Definition

```toml
[[jails]]
name = "myapp"                        # Jail name (required)
release = "15.1-RELEASE"              # Base release (clone-provisioned when @pristine exists)
path = "/jails/myapp"                 # Custom path (optional; default data_dir/jails/<name>)
hostname = "myapp.local"              # Hostname
depends_on = ["database"]             # Dependencies
tags = ["autostart", "web", "prod"]  # `autostart` is reserved; others select groups
devfs_ruleset = 4                     # devfs ruleset (default 4; 0 disables devfs)
init = true                           # Run /etc/rc at start, /etc/rc.shutdown at stop (default)
stop = "service nginx stop"           # Run inside the jail before teardown (overrides Jailfile STOP)

[jails.mount]
# Host directory mounted below the jail root through nullfs. Manifest volumes
# are always read-only, nosuid and noexec; they attach on start and detach on stop.
# The source is checked at start, and targets cannot share or nest.
volumes = ["/home/me/src/myapp:/workspace/myapp:ro"]

[jails.resources]
memory = "1g"                         # rctl memoryuse:deny
cpu = "150"                           # rctl pcpu:deny (percent)
maxproc = 200                         # rctl maxproc:deny
cores = 2                             # Pin to N least-loaded CPUs
# cpuset = "0,1"                      # Or pin to an explicit CPU list

[jails.network]
vnet = true                           # Enable VNET
networks = ["default"]                # Named networks to attach to
bridge = "blackship0"                 # Optional if runtime network state defines a bridge
ip = "10.0.1.10"                      # Static IP, or omit for auto-assignment
gateway = "10.0.1.1"                  # Optional if resolved from named network
mac_address = "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

[jails.network.dns]
nameservers = ["8.8.8.8", "8.8.4.4"]  # DNS servers
mode = "custom"                        # custom or inherit

[jails.healthcheck]
enabled = true

[[jails.healthcheck.checks]]
name = "http"
command = "curl -sf http://localhost:80/health"
target = "jail"
interval = 30
timeout = 10
retries = 3

[[jails.healthcheck.checks]]
name = "process"
command = "pgrep nginx"
target = "jail"

[[jails.hooks]]
phase = "pre_start"                   # pre_create, post_create, pre_start, post_start,
target = "host"                       # pre_stop, post_stop, pre_eva, post_eva
command = "/usr/local/bin/fetch-secrets"  # A program, not a shell line
args = ["${jail_name}"]               # also ${jail_path}, ${jail_ip}, ${jid}
on_failure = "abort"                  # abort or continue

[[jails.hooks]]
phase = "pre_stop"
target = "jail"
command = "/usr/sbin/service"
args = ["nginx", "stop"]
on_failure = "continue"
```

A hook's `command` is executed directly, with `args` as its arguments; it is
not passed through a shell, so `command = "service nginx stop"` looks for a
program by that whole name. Wrap shell syntax yourself:
`command = "/bin/sh"`, `args = ["-c", "..."]`. `post_start` hooks run after
the jail is up, so `on_failure = "abort"` there only warns: the jail keeps
running.

## 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 |
| `blackship autostart [--dry-run]` | Reconcile the project to its `autostart` tags |

Targets accept a jail name, an unambiguous prefix, a tag (from `tags = [...]`
in the jail definition), or `ALL`.

### Start at boot

Add the reserved `autostart` tag to each jail that should run after boot:

```toml
[[jails]]
name = "web"
depends_on = ["database"]
tags = ["autostart", "web"]
```

`blackship autostart --dry-run` previews the desired project state. Running
`blackship autostart` stops project jails outside that state, then starts the
tagged jails and their dependencies in dependency order. A dependency such as
`database` therefore starts at boot without needing its own tag. A jail that
fails to stop is reported at the end and never blocks the start pass. With no
`autostart` tags it stops every project jail and starts nothing.

`blackship supervise --autostart` is start-only: it starts the effective set and
never stops anything, so restarting the warden leaves a jail you started by hand
alone. Only the explicit `blackship autostart` prunes. With no tags it starts
nothing. "Started" means the jail exists and its `/etc/rc` has been launched
(`init = true`); services may still be coming up, so judge readiness by health
checks, not by the command returning.

`blackship supervise` keeps its existing behavior of starting and monitoring
every configured jail. The packaged rc service uses that behavior by default.
Enable its autostart mode to reconcile and monitor only the effective boot set:

```sh
sysrc blackship_warden_enable=YES
sysrc blackship_warden_autostart=YES
service blackship_warden start
```

The rc service runs `blackship setup` first, then launches
`blackship supervise --autostart`; it does not briefly start the entire fleet.
With no `autostart` tags, that mode starts no project jails. Leave
`blackship_warden_autostart` at its default `NO` to retain the all-jails
behavior. `ps` JSON reports both the raw `tags` and the effective `autostart`
value (including dependencies).

`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. rctl rules are replaced only when they differ from
what the kernel holds (sizes compared in bytes), and the cpuset is re-pinned.
`path`, `vnet`, and IP addresses cannot change live: drift on those, including
a VNET jail's address read from inside its stack, is reported as a
restart-required warning and skipped. Not-running jails are skipped.
`--dry-run` prints the diff without touching anything; run unprivileged, it
cannot read a VNET address or the kernel's rctl rules and lists them as
"could not be read, not verified".

| Command | Description |
|---------|-------------|
| `blackship ps [--host] [--json]` | List manifest jail status; `--host` also includes other running host jails |
| `blackship check` | Validate configuration; warn on jail releases not bootstrapped |
| `blackship capabilities` | Report binary and host capabilities |
| `blackship host` | Report the comprehensive host planning profile as JSON |
| `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>] [--dns <ip>] -- <cmd>` | Run a command in an ephemeral jail, removed when it exits |
| `blackship run --name <n> --release <r> [--network <net>] [--dns <ip>] -d` | Start an ephemeral jail and leave it running (no command; use `exec`, then `rm`) |

### File Operations

| Command | Description |
|---------|-------------|
| `blackship cp <src> <dest>` | Copy files (`jail:path` for jail paths; short or full jail name) |
| `blackship rm <jails...> [-f] [--volumes]` | Remove/destroy jails; exits non-zero if any was not removed (missing, or running without `-f`) |

### 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] [--keep]` | Move a jail to another host over ssh; fences the source |
| `blackship migrate --resume <jail>` | Finish a migration a kill or crash interrupted |
| `blackship migrate --abort <jail>` | Roll an interrupted migration back: remove the partial destination and the snapshot |
| `blackship unfence <jail>` | Lift the fence a migration left on a jail, so it can start here again |

### 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 [--autostart]` | Supervise all jails; with `--autostart`, reconcile and supervise only the boot set |
| `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 (builds a missing root through the same ZFS-aware path as `blackship build`) |
| `blackship armada down [jails...]` | Stop all jails |
| `blackship armada build [jails...]` | Build jails from Jailfiles, through the same ZFS-aware path and layer cache as `blackship build` |
| `blackship armada ps [--json]` | Show status of all jails |
| `blackship armada config [--show]` | Validate and show configuration |

`armada config --show` prints, and returns in JSON, only the project, `data_dir`,
ZFS settings and each jail's name, path, release, build and dependencies. It
never echoes secrets such as `[telemetry]` headers.

Every Armada action supports the global `--format json` contract. The result is
wrapped in the versioned JSON envelope used by other Blackship commands. For
actions that normally print progress, those lines are returned in
`data.messages` so stdout remains one valid JSON document:

```sh
blackship --format json armada -f blackship.toml up --dry-run
```

#### Config File Merging

Every manifest-aware command accepts repeated global `-c`/`--config` files.
Later files override earlier files, tables merge recursively, and named
`[[jails]]` and `[[networks]]` entries merge by `name`. This makes it possible
to keep project settings and individual jails in separate files:

```text
blackship/
├── project.toml
└── jails/
    ├── database.toml
    └── web.toml
```

```sh
blackship \
  -c project.toml \
  -c jails/database.toml \
  -c jails/web.toml \
  check

blackship \
  -c project.toml \
  -c jails/database.toml \
  -c jails/web.toml \
  eva database --dry-run
```

The first path supplies the project name when `[config].project` is omitted.
With one path, `-c blackship.toml` behaves exactly as before. Arrays other than
`[[jails]]` and `[[networks]]` replace the earlier value, a name may appear only
once per file, and errors name the offending file. Relative paths (`build`,
`jailfile`) resolve against the working directory, not the file that wrote them.
`mcp` reads only the first file; `armada` uses its own `-f` list.

Armada continues to support its command-local `-f`/`--file` spelling:

```sh
# Merge base config with production overrides
blackship armada -f base.toml -f prod.toml up

# Merge multiple files
blackship armada -f base.toml -f secrets.toml -f local.toml up
```

#### Jailfile References

Jails in `blackship.toml` can reference Jailfiles for building:

```toml
[[jails]]
name = "web"
build = "./web"              # Directory containing Jailfile
depends_on = ["db"]

[[jails]]
name = "api"
jailfile = "./custom/Api.jailfile"  # Explicit Jailfile path
```

### Shell Completion

| Command | Description |
|---------|-------------|
| `blackship completion bash\|zsh\|fish` | Generate shell completion |

### MCP Server

| Command | Description |
|---------|-------------|
| `blackship mcp [--listen addr:port]` | Serve MCP on stdio, or Streamable HTTP with `--listen` (see [MCP Server]#mcp-server-1) |
| `blackship ui [--listen addr:port]` | Placeholder web page, `--features ui` (see [Web UI]#web-ui-placeholder) |

## Jailfile Format

Jailfiles define reproducible jail builds, similar to Dockerfiles:

```dockerfile
# Jailfile
FROM 15.1-RELEASE

# Labels (metadata)
LABEL name=nginx-jail version=1.0

# Build arguments
ARG NGINX_VERSION=1.30

# Environment variables
ENV NGINX_VERSION=${NGINX_VERSION}

# Run commands (executed via jexec)
RUN pkg install -y -g "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)

```toml
# Jailfile.toml
[metadata]
name = "nginx-jail"
version = "1.0"

[build]
from = "15.1-RELEASE"

[[build.args]]
name = "NGINX_VERSION"
default = "1.30"

[[build.run]]
command = 'pkg install -y -g "nginx-${NGINX_VERSION}*"'

[[build.copy]]
src = "nginx.conf"
dest = "/usr/local/etc/nginx/nginx.conf"
owner = "root:wheel"
mode = 0o644

[[build.expose]]
port = 80
protocol = "tcp"

[start]
cmd = "/usr/local/sbin/nginx -g 'daemon off;'"

[stop]
cmd = "/usr/local/sbin/nginx -s quit"
```

The TOML format runs its steps in a fixed order, whatever order the tables
appear in: `from`, `workdir`, `args`, `env`, every `run`, every `copy`, then
`expose`. No `run` can act on a copied file, so set ownership and permissions on
the `copy` entry itself (`owner`, `mode`); when a command must follow a copy,
use the line format, which keeps the order as written. Unknown keys are
rejected rather than ignored.

### Build Commands

```sh
# Basic build
blackship build -f Jailfile -n myjail

# With build arguments
blackship build -f Jailfile -n myjail --build-arg NGINX_VERSION=1.30

# Dry run
blackship build -f Jailfile --dry-run
```

## ZFS Integration

ZFS is what makes jails cheap. With `zfs_enabled = true`:

1. Releases bootstrap into their own dataset and get a `@pristine` snapshot
2. Jail roots are `zfs clone`s of that snapshot, so creation is near-instant
   and jails share the base blocks instead of copying them
3. Jailfile builds snapshot each step, giving rebuilds a layer cache
4. `blackship commit` freezes a jail back into a reusable release
5. 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

```sh
# Bootstrap once: extracts to a dataset, snapshots it @pristine
blackship bootstrap 15.1-RELEASE

# Jails clone from it: sub-second, and nearly free on disk
blackship up web

# Configure a jail, then freeze it into a reusable release
blackship build -f Jailfile -n runner
blackship commit runner runner-golden

# Everything cloned from it starts pre-configured
blackship run --name ci-1 --release runner-golden -- ./run-tests.sh
```

`commit` promotes the new release so it no longer depends on the jail. A side
effect of `zfs promote`: snapshots the jail took before the commit move to
the release, and the jail can no longer roll back to them.

### 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.

```sh
# Create snapshot before changes
blackship snapshot create web pre-update

# Make changes
blackship exec web -- pkg upgrade -y

# If something breaks, rollback
blackship down web
blackship snapshot rollback web pre-update --force
blackship up web

# Clone for testing
blackship clone web@pre-update web-test
```

### Export/Import with ZFS

```sh
# Fast export using ZFS send
blackship export web -o web-backup.zfs --zfs-send

# Standard tar.zst export (bsdtar: hardlinks and file flags kept, sockets
# skipped, devfs and other mounts left out; a failed export leaves no file)
blackship export web -o web-backup.tar.zst

# Import (auto-detects format)
blackship import web-backup.tar.zst --name web-restored

# Import from another jail manager
blackship import old-jail.zip --from iocage --name legacy

# Move a stopped jail to another host over ssh
blackship migrate web seuros@otherbox
```

`migrate` runs as root, so the ssh connection uses root's keys and
`known_hosts`, not yours: set those up for the target first.

A migration that succeeds fences the source so the jail cannot quietly run on
two hosts: its dataset goes read-only, gets a `blackship:migrated` property
(`<host>/<dataset>@<unix time>`), and `up` refuses to start it, naming where it
went. `blackship unfence web` lifts the fence if you change your mind. A
transfer that fails fences nothing, and blackship removes the partial dataset
it left on the target. A jail cloned from a release is sent as a full copy of
its current state, without its older snapshots (the target does not have the
release to clone from). The source is never removed: `--keep` only silences the
hint about removing it yourself (`blackship rm web --volumes`). The dataset
arrives on the target with the mountpoint it had here; a target with a different
`data_dir` moves it with `zfs set mountpoint=<data_dir>/jails/<name>` (the
command prints the real source path). `gc` follows its usual rules for a fenced
dataset, so it is only reclaimed with `--force`, and its report says the dataset
was migrated and to where.

A migration is recorded at `<data_dir>/migrations/<jail>.json` from before its
first effect until it settles, so a `kill -9` (or a power cut) between the
receive and the fence leaves a trace instead of a jail that is runnable on both
hosts. While a record exists, `migrate` refuses to start the same jail again and
names the record. Then pick one:

```bash
blackship migrate --resume web   # re-check both hosts, then carry on where it stopped (or retry a parked step)
blackship migrate --abort web    # remove the destination dataset and the snapshot; the source is as it was
```

Both look at the real state first (does the destination dataset or the snapshot
exist, is the source fenced) rather than trusting the record, and neither
sends the stream twice. `--resume` also needs the jail stopped, and the source is only fenced if it has not been written to since the snapshot (otherwise the stale copy is removed and the migration rolls back). If undoing a step
fails twice (the target is down, a snapshot is held), the migration is parked: the
record stays, the error says what is left, and the attempt count is kept in the
record. Fix the cause and run `--resume` (or `--abort`) again: the parked step is
retried with a fresh run of attempts, after looking at what is really left, and the
rollback carries on in reverse until the record settles. `--resume` and `--abort` exit 0 when they settle the record (completed, or rolled back with nothing left; JSON `outcome` is `completed`, `rolled_back` or `aborted`) and nonzero when the migration is still parked, refused, or failed again. A record that does not read back as one blackship wrote is
refused and left alone. Both accept `--format json`.

## 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:

```sh
blackship network create default --subnet 10.0.1.0/24 --backend netgraph --bridge ngbridge0
```

```
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:

```toml
[jails.network]
vnet = true
networks = ["default"]
ip = "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 (see [Outbound traffic](#outbound-traffic)).

### Outbound traffic

Both backends route jail traffic through the host gateway, and Blackship
does not install NAT. Blackship sets `net.inet.ip.forwarding=1` when it
realizes a gateway; reaching anything beyond the host takes a NAT rule per
subnet in `pf.conf`, on the interface that carries the default route:

```
nat on $ext_if inet from 10.0.1.0/24 to any -> ($ext_if)
```

Without it, jails reach the gateway and each other, and nothing else.

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 Forwarding

Uses PF anchors to avoid modifying `/etc/pf.conf`:

```sh
# Expose nginx on port 80
blackship expose web -p 80

# Expose on specific host IP
blackship expose web -p 443 -I 192.168.1.100

# Different internal port
blackship expose web -p 8080 --internal 80
```

Add to `/etc/pf.conf` (`blackship setup --enable-pf` writes a minimal one
with these lines when none exists):
```
rdr-anchor "blackship"
anchor "blackship"
```

The `blackship` anchor also references the per-jail drain anchors, so these
two lines cover `[jails.drain]` and `cascade = "isolate"` as well.

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

```toml
[[jails.healthcheck.checks]]
name = "api"
command = "curl -sf http://localhost:8080/health"
target = "jail"
interval = 30
timeout = 10
```

### TCP Check

```toml
[[jails.healthcheck.checks]]
name = "postgres"
command = "nc -z localhost 5432"
target = "jail"
```

### Command Check

```toml
[[jails.healthcheck.checks]]
name = "nginx-running"
command = "service nginx status"
target = "jail"
```

### Suspicion instead of retry counting

By default a check is Failing after `retries` consecutive failures. For flaky
probes you can opt in to a phi-accrual detector per check:

```toml
[[jails.healthcheck.checks]]
name = "api"
command = "curl -sf http://localhost:8080/health"
target = "jail"
interval = 5

[jails.healthcheck.checks.suspicion]
min_samples = 8        # passing checks before phi is reported (default 8, at most 64)
unhealthy_phi = 3.0    # a failed check reports unhealthy at this phi (default 3.0)
failing_phi = 8.0      # ... and failing at this one (default 8.0)
# min_std_dev_ms = 1250  # deviation floor; default is a quarter of `interval`
```

A passing check is a heartbeat; a failing check is silence. The detector
measures how long the check has been silent relative to how regular its passes
were, and a failed check is only reported once that silence is unusual. Below
`unhealthy_phi` a failed check stays healthy, between the two it is
`unhealthy`, and at `failing_phi` it is `failing`. Until `min_samples` passes
have been seen, the check falls back to plain retry counting. Only a failing
verdict can trigger the check's `recovery` action; suspicion reports a level
and never restarts anything by itself. Rate limits are unchanged.
Leave the table out and nothing changes. `unhealthy_phi` and `failing_phi`
must be positive and `unhealthy_phi <= failing_phi`; bad values are rejected
at load.

### Bounding concurrent checks

Under `supervise`, every jail's monitor runs its checks on its own. To keep a
slow host from being buried by its own probes, cap them:

```toml
[config.rate_limit.health_concurrency]
initial = 4      # runs allowed in flight at the start (default 4)
min = 1          # the limit never drops below this (default 1)
max = 1000       # never grows above this (default 1000)
```

The limit moves by additive-increase, multiplicative-decrease: it grows by one
when a run completes while the limit is saturated, and drops to three quarters
when a run errors or takes at least half of its check `timeout`. A cycle that
finds the limit full is shed, not queued: the monitor skips it and tries again
on its next interval. Unset means unbounded, exactly as before. This applies
to `supervise` health monitors only; `up` and `down` start and stop jails one
at a time.

### Monitoring

`health` runs checks inside the jail, so it escalates to root like `exec`.
`start_period` (default 60s) counts from when the jail started, so a one-time
check on a jail that has been up for a while reports real results; within the
start period it reports `starting`, and a jail that is not running reports
`unknown`. Every completed pass saves an atomic last-known summary which
`ps --host` can read without running checks. A saved result is accepted only
when its JID matches the current jail instance.

```sh
# One-time check
blackship health web

# Watch mode (updates every 5 seconds)
blackship health --watch --interval 5

# JSON output for scripting
blackship health --json
```

## 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:

```sh
blackship gc --dry-run          # report only
blackship gc                    # reap what blackship provably owns
blackship gc --force            # also release resources it cannot prove it owns
```

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.

Blackship tags every jail dataset it creates with the ZFS property
`blackship:ephemeral`. A jail that is stopped and started again reuses its
dataset, and the tag lets the new scope record claim it again, so a supervisor
that dies after a restart is still cleaned up by `gc`. A dataset without the
tag (say, one from `build`) is never claimed that way.

`gc` also reclaims a bridge that blackship created for a VNET jail once nothing
uses it, no `--force` needed. It must be tagged into the `blackship` interface
group (blackship tags a bridge only when it creates it), have no members, and
be named by no network record, no live jail's VNET record and no
`[config.bridge]`. Bridges that predate the tag, bridges you made yourself,
and the `[config.bridge]` one are never touched, and `ng_bridge` is not
handled.

### Jail state as a chart

Lifecycle and health live in one statechart, so the order things are left and
entered is resolved by the chart, not by hand:

```mermaid
stateDiagram-v2
    state Jail {
        [*] --> Down
        state Down {
            [*] --> Stopped
            Failed --> Stopped: recover
        }
        state Up {
            [*] --> Starting
            Starting --> Running: started
            state Running {
                [*] --> Healthy
                Unhealthy
                Failing
                Suspended
            }
            Running --> Draining: drain
            Running --> Stopping: stop
            Draining --> Stopping: stop
        }
        Down --> Up: start (Stopped to Starting)
        Up --> Down: stopped (Stopping to Stopped)
        Up --> Down: fail (to Failed)
    }
```

The arrows are the `state-machines` events. `fail` leaves any Up state for
Failed, and `start` and `stopped` are the Stopped-to-Starting and
Stopping-to-Stopped moves between the two groups. Supervisor health verdicts
move the leaf among the four Running states in any direction.

Events and guards stay in the `state-machines` jail machine; the chart answers
which states a move exits and enters. `fail` from a healthy running jail exits
Healthy, Running and Up, then enters Down and Failed. Health verdicts from
`supervise` move the leaf inside Running, and `stop` releases what leaving Up
held (VNET, then the address lease) in the order the chart reports.

### 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:

```toml
[jails.qos]
transition = "healthy"      # "healthy" | "timer" | "manual"
max_startup_secs = 120

[jails.qos.startup]
memory = "4g"
cpu = "400"

[jails.qos.steady]
memory = "2g"
cpu = "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:

```sh
blackship qos web --show
blackship qos web --steady
```

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

```sh
blackship audit web
blackship audit web --json
```

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:

```toml
[telemetry]
endpoint = "http://127.0.0.1:4318"
service_name = "blackship"
metrics_interval_secs = 30

[telemetry.headers]
authorization = "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

`up` starts a jail after everything it depends on; `down` stops a jail after
everything that depends on it (with the default `cascade = "strict"`). Jails
already in the target state are skipped, and `restart` brings back the
dependents its stop took down:

```toml
[[jails]]
name = "app"
depends_on = ["cache", "database"]

[[jails]]
name = "cache"

[[jails]]
name = "database"
```

```sh
# Starts: cache → database → app (siblings in depends_on order)
blackship up app

# Stops: app → database (app depends on it)
blackship down database

# Stops only app: nothing depends on it
blackship down app
```

## Examples

### Web Application Stack

```toml
[config]
# data_dir defaults to ~/.local/share/blackship
zfs_enabled = true
zpool = "zroot"
dataset = "blackship"

[[jails]]
name = "postgres"
release = "15.1-RELEASE"
hostname = "db.local"
[jails.network]
vnet = true
bridge = "blackship0"
ip = "10.0.1.10"
gateway = "10.0.1.1"

[[jails]]
name = "redis"
release = "15.1-RELEASE"
hostname = "cache.local"
[jails.network]
vnet = true
bridge = "blackship0"
ip = "10.0.1.11"
gateway = "10.0.1.1"

[[jails]]
name = "webapp"
release = "15.1-RELEASE"
hostname = "app.local"
depends_on = ["postgres", "redis"]
[jails.network]
vnet = true
bridge = "blackship0"
ip = "10.0.1.20"
gateway = "10.0.1.1"
[jails.network.dns]
nameservers = ["8.8.8.8"]
mode = "custom"

[jails.healthcheck]
enabled = true

[[jails.healthcheck.checks]]
name = "http"
command = "curl -sf http://localhost:3000/health"
target = "jail"
interval = 30
```

### Backup and Migration

```sh
# Create snapshot
blackship snapshot create webapp v1.0

# Export for migration
blackship export webapp -o webapp-v1.0.tar.zst

# On new host
blackship import webapp-v1.0.tar.zst --name webapp
# Edit blackship.toml to add jail config
blackship up webapp
```

## 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](https://docs.gitea.com/usage/actions/overview) via [act_runner](https://gitea.com/gitea/act_runner).

#### Setup

1. Bootstrap a release:
```sh
blackship bootstrap 15.1-RELEASE
```

2. Configure act_runner with jail labels:
```yaml
runner:
  labels:
    - "freebsd-15:jail://15.1-RELEASE"
```

3. Workflows targeting `runs-on: freebsd-15` would execute in ephemeral jails.

#### How it Would Work

When act_runner receives a job with a `jail://` label, the runner could:
1. Create an ephemeral jail via `blackship run --name gitea-runner-<id> --release <release> --detach`
2. Clone the repository into the jail using `blackship cp`
3. Execute each step via `blackship exec <jail> --workdir /workspace -- <command>`
4. 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.

## Web UI (placeholder)

Not a real UI yet, just the hook. Build with `--features ui` (off by default),
then:

```sh
blackship ui                          # http://127.0.0.1:7341/
blackship ui --listen 127.0.0.1:8080
```

It serves one page and one [Datastar](https://data-star.dev) SSE stream
(`/stream`) that patches the blackship version and the running jail count
every two seconds. It is read-only and has **no authentication**, so
`--listen` refuses anything that is not a loopback address. Datastar comes
from rama itself (`rama::http::sse::datastar`), no extra crate.

## MCP Server

`blackship mcp` speaks the [Model Context Protocol](https://modelcontextprotocol.io)
over stdin/stdout, or over Streamable HTTP with `--listen`, 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

```sh
blackship mcp
```

It needs no root, and it does not require a `blackship.toml` to exist --
creating one is the point. Register it with a client:

```json
{
  "mcpServers": {
    "blackship": {
      "command": "blackship",
      "args": ["mcp"]
    }
  }
}
```

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.

### Over HTTP

`--listen` serves the same tools, prompts and resources as Streamable HTTP at
`/mcp`, so an assistant on another machine can author configuration for this
host:

```sh
# Loopback: no token needed; Host/Origin checks guard against DNS rebinding
blackship mcp --listen 127.0.0.1:7340

# Any other address requires a bearer token
BLACKSHIP_MCP_TOKEN=$(openssl rand -hex 24) blackship mcp --listen 192.168.1.10:7340
```

```json
{
  "mcpServers": {
    "blackship": {
      "type": "http",
      "url": "http://192.168.1.10:7340/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}
```

The token comes from the environment, never from argv, so it does not show up
in `ps`. Without it, `--listen` on a non-loopback address refuses to start.
`blackship:///host` describes the host and the creating tools write files on
it, so treat the token like a login. The write gate works the same over HTTP: the
approval prompt reaches the client on the session's stream, and a client that
does not declare elicitation gets a refusal and no file. The server speaks
plain HTTP; put TLS in front of it (a reverse proxy, or an ssh tunnel to the
loopback listener) when the network between you and the host is not trusted.

### Tools

Read-only, no approval needed:

| Tool | Returns |
|------|---------|
| `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 |

Facts about the host are a resource, `blackship:///host`, not a tool: one
source, read before planning. Output is compact JSON; the reader is a model.

### 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](https://modelcontextprotocol.io/specification/server/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:///host` | The live host: FreeBSD version and kernel features, CPU, memory (physical, free, ARC, swap) and what manifest jails claim, ZFS pools and free space, networks with used and free addresses, PF state and the NAT egress interface, releases, manifest and unmanaged jails |
| `blackship:///man` | The CLI manual, generated from the live command spec (stdio only) |
| `blackship:///man.kdl` | The full command tree as KDL (stdio only) |
| `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.
Over HTTP the client is remote and cannot run the CLI, so the manual is not
served there. A value the server cannot read unprivileged, such as PF state,
is `null`, never a guess.

## Troubleshooting

### Jail won't start

```sh
# Check configuration
blackship check

# Try dry run
blackship up myjail --dry-run

# Clean up failed resources
blackship cleanup myjail --force
```

### Network issues

```sh
# List Blackship-managed networks
blackship network list

# Check jail IP
blackship exec myjail -- ifconfig

# Verify routing
blackship exec myjail -- netstat -rn
```

### ZFS issues

```sh
# Verify dataset exists
zfs list | grep blackship

# Check snapshots
blackship snapshot list myjail

# Manual cleanup
zfs destroy -r zroot/blackship/jails/myjail
```

### Built files are missing after `armada up`

On ZFS, 0.4.2 and earlier built a manifest jail's `build=` Jailfile into a
plain directory at the jail root, without creating the dataset. Starting the
jail mounted the dataset over it, hiding the build. 0.5.0 and later build
through the dataset but do not repair an old root. Remove the jail twice (the
first `rm` destroys the dataset, the second clears the directory left under
it, `schg` files included), then rebuild:

```sh
blackship down <project>-myjail
blackship rm <project>-myjail --volumes
blackship rm <project>-myjail
blackship armada up --build myjail
```

### `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.

### Raw sockets and `chflags` 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](LICENSE) file for details.

## Author

Abdelkader Boudih <oss@seuros.com>