The in-stack exec broker: a request-time verb, not a socket
Status: superseded (SHC-3333, 2026-10-16). Clay ruled on 2026-10-07 that any docker.sock mount gets the deployment’s brokered socket. That socket now answers the deployment’s own service replicas (list, inspect, exec, start, stop, restart) on every runtime, and mailcow’s dockerapi uses it unpatched; see docs/app-development/docker-socket.md. Nothing below was built as written. The original status line follows. Status: open design. Nothing here is built. No code, no error code, no manifest key exists for any of it. Written 2026-08-08 while taking mailcow off the host Docker socket, so that the capability gap that work exposed is recorded once with its boundaries rather than re-derived, badly, the next time an app package reaches for
/var/run/docker.sock.
Read the status line before quoting anything below as a fact about SHC.
1. The gap, stated as narrowly as it actually is
Section titled “1. The gap, stated as narrowly as it actually is”SHC can already run a command inside a named service of a stack. A job or hook
authored with context: service + service: <name> is resolved by
core/svcexec in whichever dialect owns the stack (compose or swarm) and
routed cross-node on swarm. mailcow uses it five times (mailcow-init against
mysql-mailcow, the backup/restore jobs, mailcow-revoke-app-passwords
against nginx-mailcow, the exporter against dovecot-mailcow), and matrix
was moved wholly off the socket onto it.
Every one of those is lifecycle- or CLI-triggered: install, update, backup,
restore, socket bind/unbind, or an operator typing shc.
The uncovered shape is the other one:
an application’s own web front-end, at end-user request time, wants to run a fixed command in a named sibling service of its own stack.
There is no request-time RPC an app container can call. That is the whole gap. It is not “apps cannot run containers”; see §5, which is a different problem this proposal deliberately does not solve.
What actually demands it today
Section titled “What actually demands it today”mailcow’s UI, and only in features that are already dead in SHC’s
packaging for an unrelated reason (COMPOSE_PROJECT_NAME is set in no service
environment, so functions.docker.inc.php’s project filter matches nothing):
the mail-queue page (list/flush/delete/hold/deliver), container
start/stop/restart, IMAP ACL editing, the sieve viewer, maildir cleanup, the
rspamd worker-password change, and the dashboard’s vmail df tile.
This is not what unblocked mailcow. mailcow installs, updates, sends and receives mail, authenticates and serves SOGo with none of it, and has done for as long as that variable has been unset. Conflating “restore these” with “install the app” is how a nice-to-have acquires a false urgency.
2. Shape
Section titled “2. Shape”An exec broker: a unix socket the daemon serves, bind-mounted into services that a package explicitly declares as consumers.
# in an app package's compose.yaml, hypotheticallyx-shc-exec: consumer: php-fpm-mailcow verbs: postfix.mailq.list: service: postfix-mailcow argv: ["/usr/sbin/postqueue", "-j"] postfix.mailq.delete: service: postfix-mailcow argv: ["/usr/sbin/postsuper", "-d", "{qid}"] params: qid: hex-qid # a TYPE, checked by the daemon dovecot.acl.get: service: dovecot-mailcow user: vmail argv: ["doveadm", "acl", "get", "-u", "{mailbox}"] params: mailbox: mailbox-addressRequest payload is {verb, params}: a verb, never argv. The daemon
resolves the verb through the package’s own allowlist and substitutes only
into declared, typed slots. It never concatenates strings; DockerApi.py’s
"/usr/sbin/postsuper " + sanitized_string is precisely the shape being
replaced.
Resolution reuses core/svcexec unchanged. The broker is a request-time
front door onto the machinery context: service already drives at lifecycle
time; it is not a second implementation of container lookup.
3. Why this is not the socket with extra steps
Section titled “3. Why this is not the socket with extra steps”| host Docker socket | exec broker | |
|---|---|---|
| reachable targets | every container on the host, every tenant | the calling deployment’s own services |
| selector | container name; Docker’s filter is a SUBSTRING match, so dovecot-mailcow matches every project’s dovecot | service name, resolved by SHC from the caller’s own deployment |
| commands | anything, plus create / run / build / image and volume ops | the verbs the package declared, with typed params |
| privilege obtained | host root | run one declared command in one declared sibling |
| review point | none: a bind is a bind | the verb list is in the package, diffable at pin-bump |
Two gates, and they have to be both:
- The verb allowlist is part of the app package. A new verb is a package change, reviewable in the catalogue and visible in a pin-bump diff, not a runtime grant.
- The caller is authenticated by which container the connection arrived from. Tenant, stack and environment come from the daemon’s own view of the peer, never from the request. The endpoint is bind-mounted only into declared consumers, so possession is the credential and it cannot be forwarded to a service that did not declare it.
Rate-limit and audit every call through modules/audit.
Hard nos
Section titled “Hard nos”Free-form argv. create / run / build. Any image or volume operation.
Cross-stack or cross-tenant targets. A container name as the selector.
Any of them and this is the socket again, with a manifest key in front of it.
4. Honest open questions
Section titled “4. Honest open questions”- Where does the socket live in the container, and what owns it? A per-service bind implies the daemon materialises a socket per declared consumer, which is new plumbing on the deploy path, not a free ride on an existing mount.
- Swarm.
core/svcexecroutes cross-node, but a broker socket is on ONE node’s filesystem. A consumer replica scheduled elsewhere has no endpoint. Loopback HTTP with a per-deployment token has the opposite trade (a token can be forwarded, which §3’s peer-identity gate exists to avoid). Unresolved. - Param types.
hex-qidandmailbox-addressare the two mailcow needs; a type vocabulary that grows per app is a validation surface that will drift from the validators. Better answered by a small closed set that refuses anything else than by an extensible one. - Is one app enough demand? Today the entire measured demand is one app’s already-broken UI pages. That is thin. Build it when a second, live consumer exists, or when an app that cannot ship at all without it appears.
5. What this does NOT cover, and must not be cited for
Section titled “5. What this does NOT cover, and must not be cited for”Apps whose core function is spawning containers. gitlab-runner binds the
socket read-write and templates the same bind into every job container it
starts; windmill-worker binds it to run docker-mode jobs, i.e. it hands the
host daemon to arbitrary user-authored scripts. Both are in
tests/unit/modules/app/catalog_swarm_loader_test.go’s hostBindRefused
ledger and both stay there.
Neither is a verb-in-a-sibling-service problem. Their need is “create new containers from arbitrary images with arbitrary configuration”, and no allowlist of fixed verbs against pre-existing services addresses it. The answers for those are a different question entirely (a nested/rootless runtime, a dedicated build node, or an honest refusal), and pointing at this document as their solution would be wrong.
6. Status of the thing that prompted this
Section titled “6. Status of the thing that prompted this”mailcow is off the socket and installable, without any of the above:
ofelia-mailcow’s bind was read by nothing (its entrypoint is a sleep
loop), and dockerapi-mailcow now pins docker-py’s API version so its client
constructor stops pinging the daemon at import, which lets it serve the two
functions that were ever live here (the prerequisites.inc.php TCP gate on
dockerapi:443 and the pure-psutil /host/stats) with no socket present.
See the block above dockerapi-mailcow in apps/email/mailcow/compose.yaml.
Nothing in this document is required for that, and nothing in this document has been built.