sgit serve: container first. Options map and spike results

Date: 2026-10-12 · Status: options and plan, no sgit code yet · Supersedes the "native server" plan in research__sgit-serve-local-vault-server.md (same folder). The API inventory and browser notes there still apply.

Decision (Dinis): run a working vault locally from the SG/Send container image. It has the vault UI and the API in one image and always tracks the latest SG/Send. sgit gets native support for it:

• it abstracts the container runtime;
• it supports several runtimes, including Apple's container;
• it can install one when none is present;
• it should also work without Docker where possible.

The current read-only server stays as a separate, clearly named mode.

Update, same day: decisions taken and phase 1 built.

• Decisions:

1. Image latest, with the digest that ran recorded.
2. sgit serve install installs, after showing what and asking.
3. Both Apple container and Podman are supported on macOS.
4. sgit vault serve moved to sgit serve --static.
5. The brief to SG/Send is in this folder.

• What changed from the plan below: the clone does not push to the local server as a second remote. Its rewind baselines and its copy of the server's ref are kept per branch, not per server, so two servers would trip its own rewind protection. Instead:
• sgit serve push (clone → server) only ever moves the local server forward;
• sgit serve pull (server → clone) fetches, verifies, checks the signature policy and fast-forwards this clone's own branch;
• sgit push then reaches the real server as usual.
• Verified here:
• Docker end to end: start, the UI opening the served clone, a server-side commit brought back, stop;
• the uv engine (same data folder);
• divergence refusals.

The Apple container adapter is written to its documented CLI but not yet run on a Mac.

1. Two modes

• Static mode still has a job: it previews what sgit publish produces, or serves an unpacked published zip, with zero dependencies.
• It is not "run a vault". Rename it, and make sgit vault serve print its new place (the rule-9 moved-word behaviour).

2. What I verified today (spike in this cloud container)

All of it was run here, x86_64 Linux, Docker 29.6 / containerd 2.2. The screenshot spike__local-container-ui-open-vault.png is next to this file.

3. Runtimes: what exists and how sgit would drive each

"docker-compatible" means it accepts run -d --name -p -v --user -e, ps, stop, logs and pull with the same flags, so one adapter covers all of them. Rows marked † come from my knowledge rather than today's run; check each against its current docs when building the adapter.

Detection order: a runtime already running wins. Otherwise the order is:

1. docker (context answers)
2. podman
3. container (Apple)
4. nerdctl
5. finch
6. the Python engine if uv is found
7. --static as the last resort, with a message saying what the user is missing

sgit serve --runtime <name> overrides the choice. sgit serve runtimes lists what it found, and for anything missing, the one install command per OS.

Installing:

• sgit serve install [<runtime>] prints the command and runs it only after a yes, because it is a system change.
• On macOS with Apple silicon it suggests Apple container, or Podman.
• On Linux it suggests Podman or Docker Engine.
• On Windows it suggests WSL2 + Podman.
• Without any runtime, it suggests uv and the Python engine.

4. What sgit serve does (container mode)

sgit serve                     # inside a clone
  1. pick a runtime (§3); pull the image, pinned by digest and recorded (latest by default; --tag vX.Y.Z)
  2. data dir: <clone>/.sg_vault/serve/ (or --data DIR, interchangeable with any sg-send-vault /data)
  3. run: --name sgit-serve-<vault_id> --user <uid>:<gid> -p 127.0.0.1:<port>:8080 -v <data>:/data
          (-p on 127.0.0.1 only: a plain `-p 8080:8080` publishes on every interface)
  4. wait for /api/info/health
  5. seed: push this clone into it as a remote, `local` → http://127.0.0.1:<port>
           (the existing push code: no coupling to the server's disk layout)
  6. print the UI URL, the vault-key and access-key hints; --open launches the browser
sgit serve status | logs | stop | update     # update = pull the newer image, restart, same data dir
sgit serve --static                          # today's read-only published-folder server

Then:

• sgit pull --remote local brings edits made in the browser into the clone, with full verify-then-accept;
• sgit push sends them to the real server.

The server owns its own store. The clone's .sg_vault/bare/ is never mounted, because the UI writing the clone's accepted refs would undo what 0.21 fixed.

Python engine: steps 1 and 3 become uv run --python 3.12 --with sgraph-ai-app-send==<v> python -m … --port <p>, with SEND__STORAGE_MODE=disk, SEND__DISK_PATH=<data> and SEND__VAULT_STATIC_DIR=<ui dir>. Everything else is the same.

TLS: only for the LAN or Safari cases (see the research note §5–6).

• sgit generates a cert with cryptography;
• it mounts the cert and key at /certs;
• it sets FAST_API__TLS__ENABLED=true, which the image already supports.

5. Asks of the SG/Send team (from the spike)

1. Vendor the dev.tools.sgraph.ai scripts into the image (#8). Today the "self-contained" UI needs the internet.
2. allow_private_network=True in the CORS middleware (#13). Without it, the hosted UI cannot reach a local server from Chrome.
3. No stack traces in error responses (#14), or only behind a debug flag.
4. README: the image runs as uid 10001, so document --user or chown (#4).
5. Also publish to GHCR or ECR Public (#11). sgit can then fall back when Docker Hub rate-limits.
6. Publish the built vault UI (/app/static_vault) as a versioned release asset. That is what the Python engine needs; today it can only be copied out of the image.
7. Optionally, let #<vault-key> (or a ?key= handoff) auto-open on /en-gb/vault/ (#7), so sgit serve --open lands inside the vault.

6. Changes in sgit

Estimate:

Total: about 5 days. Phase 1 alone gives you "clone a vault, sgit serve, edit it in the browser".

7. Decisions for you

1. Image tag: default to latest (always current, as you suggested) and record the digest in use, or pin per sgit release for reproducibility? My suggestion: latest, plus --tag and a recorded digest.
2. Installing runtimes: print the command only, or run it after confirmation?
3. Apple container vs Podman as the macOS recommendation: Apple's needs macOS 26 on Apple silicon; Podman runs everywhere.
4. --static naming: keep sgit vault serve as an alias, or move it fully?
5. Should I send the §5 asks to the SG/Send team as a brief?

Sources

• Apple container: https://tessl.io/registry/skills/github/sanjay3290/ai-skills/apple-container (community summary of apple/container: Apple silicon only, macOS 26 supported, macOS 15 with reduced networking, signed .pkg + container system start)
• Docker Hub pull limits: https://docs.docker.com/docker-hub/download-rate-limit/, https://oneuptime.com/blog/post/2026-03-20-portainer-docker-hub-anonymous-auth/view
• Chrome Local Network Access and Safari localhost blocking: the sources in research__sgit-serve-local-vault-server.md.

This page as markdown · its source, admin/content/articles/sgit-serve-container-first.md