Machinectl
@shrug/machinectlv2026.07.11.2
01README
Reach inside a systemd-nspawn machine over SSH+nsenter: snapshot state, run an argv, read/write files atomically (with backup), and restart/inspect units — a reusable container transport.
02Models
@shrug/machinectlv2026.07.11.2machinectl.ts
Global Arguments
| Argument | Type | Description |
|---|---|---|
| host | string | SSH host running the nspawn machine (e.g. 192.0.2.10) |
| machine | string | systemd-nspawn machine name as `machinectl list` shows it (e.g. web1) |
| user | string | SSH username; must be able to run machinectl + nsenter (root) |
| port | number | SSH port |
fn snapshot()
Read-only snapshot of the machine: leader PID, running state, system state, uptime, OS.
fn readFile(path: string)
Read a file from inside the machine (binary-safe; base64 over the wire).
| Argument | Type | Description |
|---|---|---|
| path | string | Absolute path inside the machine |
fn writeFile(path: string, content: string)
Write a file inside the machine atomically (temp+mv), with optional backup, mode, and owner.
| Argument | Type | Description |
|---|---|---|
| path | string | Absolute destination path inside the machine |
| content | string | File content (UTF-8) |
fn run(stdin?: string)
Run an argv inside the machine (no shell unless you pass one); returns code/stdout/stderr. NOTE: the full argv is recorded in the `attempt` audit resource in cleartext — do NOT pass secrets as argv elements (e.g. `mysql -p <pw>`); pipe them via `stdin` instead, which is never logged or audited.
| Argument | Type | Description |
|---|---|---|
| stdin? | string | Optional stdin piped to the command (not logged/audited — use for secrets) |
fn serviceStatus(unit: string)
Report a unit's active state inside the machine (`systemctl is-active`) — read-only.
| Argument | Type | Description |
|---|---|---|
| unit | string | Unit name, e.g. nginx |
fn serviceRestart(unit: string)
Restart a unit inside the machine, then report its post-restart active state so callers can gate.
| Argument | Type | Description |
|---|---|---|
| unit | string | Unit name, e.g. nginx |
Resources
machine(infinite)— Read-only snapshot of an nspawn machine's runtime state
fileContent(infinite)— Contents of a file read from inside the machine
sensitiveFileContent(infinite)— Contents of a file with the whole record vaulted (sensitive=true)
writeResult(infinite)— Outcome of an atomic writeFile
commandResult(infinite)— Outcome of a generic run
serviceResult(infinite)— Outcome of a serviceStatus / serviceRestart
attempt(infinite)— Audit record of a mutation attempt (argv + result/error + timestamp). Written on both success and failure.
03Previous Versions
2026.07.11.1Jul 11, 2026
04Stats
A
100 / 100
Downloads
0
Archive size
23.0 KB
- Has README or module doc2/2earned
- README has a code example1/1earned
- README is substantive1/1earned
- Most symbols documented1/1earned
- No slow types (deprecated)1/1earned
- Dependencies pass trust audit2/2earned
- Has description1/1earned
- Platform support declared (or universal)2/2earned
- License declared1/1earned
- Verified public repository2/2earned
05Platforms
06Labels