README: document nesting — the nested-container-hop feature (V2)

The README covered only single-host use; the differentiator from a shell helper
— reaching into containers several hops deep with the argv frame preserved at
every layer — was undocumented. Add a Nesting section (host/guest/svc syntax,
/etc/sic/hosts.toml nest stanzas, and the quoting-hell contrast with the ssh
equivalent), surface it in the intro line, and link docs/design-nested.md.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EWpfhDgYNA21tETDP9ueBE
This commit is contained in:
Markus Fritsche
2026-07-24 09:22:24 +02:00
parent 62ed5a1c08
commit ef1d6b517d
+35 -1
View File
@@ -1,6 +1,7 @@
# sic # sic
Run a command on a remote host without a shell re-parsing its arguments. Run a command on a remote host — or inside a container several hops deep —
without a shell re-parsing its arguments.
`ssh host touch 'a b'` creates two files: `ssh` joins its arguments with spaces `ssh host touch 'a b'` creates two files: `ssh` joins its arguments with spaces
and hands the result to the remote login shell, which splits it again. `sic host and hands the result to the remote login shell, which splits it again. `sic host
@@ -50,6 +51,38 @@ sic host1 echo '$HOME' # literal, no expansion
sic --sh host1 'echo hi | wc -c' sic --sh host1 'echo hi | wc -c'
``` ```
## Nesting
The frame survives being wrapped again, so `sic` reaches *into* containers with no
shell anywhere in the path, at any depth. A target is a host followed by container
hops separated by `/`:
```
sic host1/app cat /etc/os-release # into the 'app' guest on host1
sic host2/ct/svc touch 'a b' # host2 -> ct -> svc, ONE file, three layers deep
```
Each host's hop runtimes come from `/etc/sic/hosts.toml`, one stanza per host:
```toml
[host1]
nest = ["incus"] # host1/app -> incus exec app -- <argv>
[host2]
nest = ["pct", "docker"] # host2/ct/svc -> pct exec ct -- docker exec svc -- <argv>
```
This is what separates `sic` from a shell helper script. The `ssh` equivalent —
```
ssh host2 "pct exec ct -- docker exec svc -- touch \"a b\""
```
nests quotes inside quotes inside quotes, and every layer re-splits the arguments; a
body containing a space, `$()`, a pipe, or a newline breaks a different layer each time.
`sic` frames the argv once and re-frames it at each hop, so `touch 'a b'` is one file
whether it runs on the host or three containers deep. No escaping, at any level.
## Build ## Build
``` ```
@@ -88,5 +121,6 @@ sic host echo hello world
## See also ## See also
- `docs/design.md` — wire format, exec modes, transport and security, prior art. - `docs/design.md` — wire format, exec modes, transport and security, prior art.
- `docs/design-nested.md` — how nested container hops resolve.
- `demos/quoting-hell.py` — six cases run both ways, plain `ssh` versus `sic`. - `demos/quoting-hell.py` — six cases run both ways, plain `ssh` versus `sic`.
- `SKILL.md`, `SKILL-bg.md` — agent skill definitions (foreground and background). - `SKILL.md`, `SKILL-bg.md` — agent skill definitions (foreground and background).