Phase 1 finished - dev sandbox only

Kanthor Core local sandbox architecture

This page visualizes the completed Phase 1 scope: a rootless Podman development sandbox, its C4 architecture, and the working flows proven by the smoke harness. It intentionally does not describe future Core product internals.

Podman rootless Node 24 image .data boundary TCP host fallback UDS container-to-container

C4 Model

Phase 1 is shown at Context, Container, and Component levels. The component level is the smoke harness, not product Core.

C4 context diagram for Phase 1 Developer interacts with Kanthor Core dev sandbox through make commands, host TCP, and optional container client UDS. The sandbox writes only to .data on the host. System Context The sandbox protects the host tree while keeping data inspectable. Kanthor Core dev sandbox Podman - Node 24 - rootless Runs the Phase 1 smoke harness until real Core exists Developer make up - verify - logs Host client TCP 127.0.0.1:7777 Container client UDS named volume Host-visible .data/ database - logs - auth - cache make published TCP shared socket only host mount
C4 container diagram for Phase 1 Container view showing the Podman VM, dev server container, optional client container, host .data bind mount, and named socket volume. Container View Two supported dev modes share the same image and host data boundary. Podman machine on macOS - applehv provider kanthord-dev image COPY scripts/dev/*.mjs No source bind mount server container smoke.mjs TCP + UDS + writes client container uds-client.mjs compose mode only sock named volume /data/sockets macOS host .data/ bind mount database/ - logs/ - auth/ - cache/ - host-owned via --userns=keep-id run image UDS persistent host-inspectable data
C4 component diagram for Phase 1 smoke harness Smoke harness components exercise atomic write, auth permissions, UDS server, TCP server, and host probe. Component View: Phase 1 Smoke Harness These components prove the sandbox boundary; they are not the final Core modules. scripts/dev/smoke.mjs inside server container data layout mkdir sockets/database/logs atomic write tmp -> rename UDS server echo over socket TCP server 0.0.0.0:PORT .data/ files DB - logs - credential probe-host.mjs host-side verification
make / host data operations
TCP path
volume / file boundary
UDS path

Working Flows

The completed phase supports two ways to run the sandbox. The animation highlights the active transport and storage boundary.

Mode A: run Core stand-in inside Podman, then connect from the Mac host through the published TCP port.
A

Entry point

`make up` creates `.data/`, starts `kanthord-dev`, and publishes `127.0.0.1:7777`.

B

Supported host transport

The host probe expects TCP to pass. UDS across macOS host -> VM is documented as unreliable and not fatal.

Single container host TCP flow Mac host starts Podman container. Host probe connects to the container over TCP and reads generated files from .data. macOS host make verify probe-host.mjs TCP + file reads server container smoke.mjs TCP echo 0.0.0.0:7777 .data/ database - logs - auth - cache 127.0.0.1:7777
Mode B: run server and client in containers, sharing a Podman named volume for the Unix domain socket.
A

Socket location

The socket lives at `/data/sockets/kanthord.sock` on the named `sock` volume, not in the host bind mount.

B

Why it matters

UDS works container-to-container over the named volume, avoiding the macOS virtiofs host boundary.

Compose UDS flow Server and client containers communicate through a Unix domain socket on a named volume while the server writes persistent files to .data. server container smoke.mjs listens on UDS client container uds-client.mjs pings socket every 5s sock named volume /data/sockets/kanthord.sock host .data/ bind remains for DB, logs, auth, cache uds-echo:ping

Sequence Diagrams

These animated sequences show the actual Phase 1 commands and stand-in scripts.

Developer
Makefile
Podman
smoke.mjs
.data/
make verify
podman build + run
start server
mkdir + tmp rename + chmod
files visible
smoke_ready logs
probe TCP 127.0.0.1:7777
read DB + auth perms
Developer
Compose
Server
sock volume
Client
make compose-up
start server
listen kanthord.sock
start client
connect socket
ping-from-client
uds-echo reply
logs show uds_ok

Boundary Proofs

Phase 1 is mainly about proving the local development safety boundary before real product code exists.

1

Host safety

The running container receives copied source from the image. The host source tree is not bind-mounted, so container tools cannot mutate it.

2

Data ownership

`--userns=keep-id` keeps `.data/` files host-owned with auth directory `0700` and credential file `0600`.

3

Transport decision

TCP is the supported Mac host path. UDS is supported inside the sandbox between containers via the named `sock` volume.

.data/database/smoke.jsonWritten with temp-then-rename to exercise atomic file database writes on the mounted filesystem.
.data/logs/smoke.jsonlAppend-only operational events such as `smoke_ready`, `tcp_listening`, and `uds_listening`.
.data/auth/credentialPermission check for secret material: file mode `0600`, directory mode `0700`.
sock:/data/socketsCompose-only named volume for UDS so socket traffic stays off the macOS virtiofs boundary.

Phase 1 Commands

The commands below map directly to the architecture shown above.

make machine-upStart the Podman VM once per boot.
make upStart the single server container and publish TCP on `127.0.0.1:7777`.
make verifyBuild, run, probe host TCP and mounted files, then tear down.
make compose-upStart server and client containers with the shared UDS named volume.
make compose-logsWatch server events and client `uds_ok` messages.
make resetDestructive cleanup for `.data/`; only use when you intend to wipe local sandbox data.