Skip to content
SHC Docs

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.

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.


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, hypothetically
x-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-address

Request 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 socketexec broker
reachable targetsevery container on the host, every tenantthe calling deployment’s own services
selectorcontainer name; Docker’s filter is a SUBSTRING match, so dovecot-mailcow matches every project’s dovecotservice name, resolved by SHC from the caller’s own deployment
commandsanything, plus create / run / build / image and volume opsthe verbs the package declared, with typed params
privilege obtainedhost rootrun one declared command in one declared sibling
review pointnone: a bind is a bindthe 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.

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.


  • 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/svcexec routes 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-qid and mailbox-address are 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.


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.