bri-sandbox-development-platform/AGENTS.md

AGENTS.md — Sandbox Deployment Platform

Build, lint, test

The build script is the only way to compile — local Go can't fetch the 1.24 toolchain. Run:

./scripts/build.sh        # cross-compiles 3 Go binaries + builds the Next.js dashboard
./scripts/deploy.sh       # SSHes artifacts + systemd units to 92 and 186, then enables+starts them; needs sshpass

The script uses a golang:1.24-alpine container with a persistent sdp-gocache named volume. GO_IMAGE=... overrides the image. Outputs: bin/{control-plane,agent-micro,agent-gateway} (Linux/amd64, static) and dashboard/out/.

Per-module Go work uses the same container:

docker run --rm -v "$PWD:/src" -w /src/<module> golang:1.24-alpine sh -c \
  "apk add --no-cache git >/dev/null && git config --global --add safe.directory /src && go vet ./..."

For a single test:

docker run --rm -v "$PWD:/src" -w /src/control-plane golang:1.24-alpine sh -c \
  "apk add --no-cache git >/dev/null && git config --global --add safe.directory /src && go test ./internal/store/..."

There is one test file today: control-plane/internal/store/store_test.go (round-trips all Slice-2 CRUD).

The dashboard has no separate typecheck or lint script — npm run build runs both. cd dashboard && npm run build locally is fine; node_modules is gitignored.

Layout

Five Go modules in a workspace (go.work):

• protocol/ — wire types shared by CP and agents. Keep small.
• agentlib/ — gitutil (askpass-via-stdin credential helper; git ls-remote, fetch, checkout, pull, for-each-ref, reset --hard) and deployer (per-deployment state machine; NewGo for microservices, NewPHP for erangel).
• control-plane/ — HTTP API + WS hub + SQLite. Routes split across internal/api/{login,sandboxes,templates,environments,routes,deployments,repos}.go. internal/ws/hub.go exposes CallAgent for sync RPCs.
• agent-micro/ — runs on 172.18.136.92.
• agent-gateway/ — runs on 172.18.139.186; owns erangel at /var/www/html/erangel-ocean and the <service>_url patching.
• systemd/ — unit files for the three long-running services (sdp-control-plane.service, sdp-agent-micro.service, sdp-agent-gateway.service). All three are plain host processes managed by systemd; the agents talk to the host's dockerd via /var/run/docker.sock to spawn the actual service containers (sdp-<repo>) for each deploy. Service containers are NOT managed by systemd — that's docker's job.

Dashboard is a separate next build static export under dashboard/src/app/. Static export means dynamic routes need generateStaticParams (see the sandboxes/[id] page for the pattern).

Wire protocol

The agent → control-plane channel is one protocol.Event per WS text message. The control-plane → agent channel is an ad-hoc envelope {op, id, data}. op values: deploy, stop, list_repos, list_branches, list_routes, probe, push_routes. RPC replies have {op:"reply", id, ok, error?} and a data field. The two shapes are disambiguated by kind (event) vs op (rpc reply). New ops go in agentlib/.../main.go's switch and the control-plane's repos.go / sandboxes.go / routes.go handlers — there is no central registry.

Conventions

• ponytail: comments mark intentional shortcuts and "TODO: real impl"-style carve-outs. They survive into main. Don't remove without fixing the underlying limitation.
• Slice-2 stable container name: sdp-<repo> (no deployment id). The next deploy force-removes the existing one. One live container per repo at a time.
• Gateway agent persists the per-branch OCP-default snapshot to <repoPath>/.sdp/ocp-defaults.json. Re-captured on every deploy so branch switches don't break "Restore OCP" buttons.
• NewPHP runs git reset --hard before fetch (via Spec.PreGitReset), and the agent passes an AfterStart closure that re-applies active route overrides after the container is up. This is what survives git reset --hard + checkout.
• protocol.Event.ContainerID is set on the deployer side; the deployer writes it back via Store.SetContainerID. (Currently the field on the event is unused; container id is recorded in SQLite.)
• Cookie auth: sdp_session HttpOnly cookie; the withAuth middleware skips /api/login. WebSocket endpoints are NOT auth-gated by the middleware — they rely on the agent being on a private network.
• Crendentials travel with each deploy/probe/push_routes frame from control plane to agent. Never logged. Never persisted on the agent.

Gotchas

• Host Go (/usr/bin/go) is older than the go 1.24 modules require and the toolchain download is blocked. Use the golang:1.24-alpine container. Do not edit code expecting go build to work locally.
• The micro agent and gateway agent main.go files duplicate most logic (dial / writer / readLoop / runDeploy). The shared code is in agentlib/. When adding a new op, both files need a switch case.
• moby/moby/client v0.5.0 uses netip.Addr for PortBinding.HostIP, not a string.
• sdp-<repo> containers must be in a state where docker rm -f works (the Slice-2 "one live per repo" rule). Don't manually docker run a second container with the same name.
• The erangel repo path is /var/www/html/erangel-ocean on 186, NOT ~/SDP (README's earlier value is wrong; the spec was fixed in Slice 2). APACHE_DOCUMENT_ROOT is set to the same path so the gateway is served at /erangel/.
• agent-gateway/.../main.go re-imports the routesState type and uses rs as both a value and a parameter name in some helpers. Compiles fine; just be aware when grepping.
• Static-export dynamic routes: generateStaticParams must return at least one placeholder; the actual id is read at runtime in the client component. See dashboard/src/app/dashboard/sandboxes/[id]/.

Verifying changes locally

# Typecheck + build everything
./scripts/build.sh

# Run the only Go test
docker run --rm -v "$PWD:/src" -w /src/control-plane golang:1.24-alpine sh -c \
  "apk add --no-cache git >/dev/null && git config --global --add safe.directory /src && go test ./..."

# Smoke the control plane
./bin/control-plane -addr :3452 -data /tmp/sdp-data &
curl -i -X POST http://127.0.0.1:3452/api/login -d '{"username":"x","password":"y"}'
# Expects 401 ("login failed — git ls-remote rejected") when no gateway agent is connected.

Out of scope

RBAC, suspend/resume, sandbox cloning beyond "clone template into sandbox", per-sandbox Docker networks, per-sandbox resource limits, health monitoring, the 172.18.136.93 infra agent, notifications. These are listed as later in REQUIREMENTS.md.

Do not

• Do not commit or push unless the user explicitly says "commit" or "push".
• Do not change the gateway repo path back to ~/SDP (old docs say so; reality is /var/www/html/erangel-ocean).
• Do not rebuild the dashboard via next start for production; the output is served by nginx on 186. Configure nginx by hand; the reference config is in nginx/nginx.conf and uses root /home/administrator/SDP/dashboard; (i.e. the path deploy.sh scp's the static export to).
• Do not log or persist Bitbucket creds anywhere.