deepseek-kubernetes-sandbox/.dsh/skills/dsh-agent-sandbox-platform/references/extending-the-repo.md

Extending the repository

Read AGENTS.md, docs/examples.md, and the example README before editing. This repository is image-first: the Dockerfile is the primary artifact, every implementation is a self-contained example under examples/<name>/, and versions.env is the only source of pins. Documentation is part of the change.

Invariants

• Never hard-code a version, image tag, or registry path; edit versions.env. For the DSH release identity use make set-version, never ad-hoc sed.
• Never commit a secret. Secret-shaped manifests are *.yaml.example with placeholders; keys are documented only in .env.sample.
• Manifests are numbered NN-*.yaml and apply in order with plain kubectl. Exposure variants live under manifests/exposure/<variant>/, are documented by one README, and are mutually exclusive.
• Keep the gateway HTTP/WebSocket contract stable unless the change is explicitly about it.
• Do not edit CHANGELOG.md (generated by git-cliff) or rewrite git history.
• Keep diffs scoped; do not mix a version bump with an unrelated feature.

Change matrix

Change	Edit	Minimum verification
Documentation only	*.md, docs/	make check; relative links resolve
Example manifest	examples/<name>/manifests/NN-*.yaml, README step	make check; server-side dry-run in CI
Gateway behavior/route	gateway/gateway.py, gateway/test_gateway.py, gateway README, architecture	make test, make lint; update tests and API docs
Exposure variant	manifests/exposure/<variant>/, exposure README, example README	make check; apply exactly one variant
New example	full examples/<name>/ layout, examples/README.md	make check; CI dry-run; optional e2e
Version bump	versions.env, affected docs/manifests	make check; CI installs the pin; e2e on a cluster
MCP integration	deployment/RBAC, DSH row, docs	read-only /readyz; no secret in repo
Workflow	.github/workflows/	actionlint; SHA-pinned actions; no hard-coded versions

Recipes

Add or change a resource step

1. Keep numbering stable; add NN-*.yaml at the end unless order matters.
2. Update the matching numbered step in the example README.
3. Keep cluster-specific state (node affinity, tuned replica counts) out of the shipped manifest; document it as a local patch.
4. Run make check. CI additionally parses every manifest and runs a server-side dry-run against the agent-sandbox CRDs.

Change the gateway

The gateway is a single-file Starlette app. A change usually touches:

• gateway/gateway.py (route, auth, proxy, sweeper);
• gateway/test_gateway.py (unit tests; no cluster required);
• gateway/README.md (API table, configuration, auth semantics);
• examples/dsh-agents-as-a-service/docs/architecture.md when flows change;
• examples/dsh-agents-as-a-service/README.md when the walkthrough changes.

Run make test and make lint. Preserve session-cookie auth, same-origin rules for cookie mutations and WebSocket upgrades, and the "waking"/502/503 semantics unless the change is explicitly about them. Do not expose a trusted identity header unless the Service is reachable only through the proxy.

Add an exposure variant

Create manifests/exposure/<variant>/NN-*.yaml, update manifests/exposure/README.md and the example README, and state the trust boundary. Variants are alternatives: never apply two paths to the same gateway. Set DSH_TRUSTED_HOSTS in the template for the public host and COOKIE_SECURE=true for HTTPS.

Add an example

Follow docs/examples.md: README.md, manifests/NN-*.yaml, optional manifests/exposure/ with a README, optional components with Dockerfile + README + tests, and executable, idempotent, self-cleaning scripts. Add the literal examples/<name>/ entry to examples/README.md; make check enforces the layout. Publish component images under <registry>/<owner>/<repo>/<example>/<component>.

Bump a version

• DSH release identity: make set-version DSH_VERSION=<ref> [RELEASE_REVISION=rN], then make check, then build and smoke-test the image. Tags are immutable; fix a bad release with -r(N+1).
• agent-sandbox: edit AGENT_SANDBOX_VERSION in versions.env, update the prerequisites in the example README, and note behavior changes (connection types, MCP output limits, CRD fields). Install the new release YAML on a kind cluster, then run make check and make e2e. Do not bump it inside an unrelated PR.

Integrate the agent-sandbox MCP server

Build from the cluster's pinned tag, give it a dedicated namespace and least-privilege ServiceAccount, keep it ClusterIP behind an authenticating proxy, and document how to reach /readyz. Add a DSH profile row only with user approval; a row affects every session. Never commit its credentials or a cluster-admin binding.

Documentation

Update the doc whose behavior changed in the same commit: root README for the front door, docs/ for repository-wide contracts, the example README for that walkthrough, the gateway README for API/config/auth. Skill docs live in .dsh/skills/; keep SKILL.md under ~8 KB and put depth in references/. scripts/check-versions.sh scans every *.md for stale dsh-v… tokens, so refer to "the release identity in versions.env" rather than copying a tag.

Verification and review

Run at least make check; add make test and make lint for gateway/script changes. For manifests, use kubectl apply --dry-run=server against a cluster with the CRDs. For behavior changes, run the example or make e2e.

Before reporting, review:

• Diff is scoped; no generated files or unrelated changes.
• Docs and examples match the new behavior.
• Pins come only from versions.env; no stale version tokens.
• No secrets or usable credentials; secret-shaped files are .example.
• Manifests parse; exposure variants remain mutually exclusive.
• Gateway tests and public contract unchanged or intentionally updated.
• Skills: frontmatter valid, body within budget, scripts shellcheck-clean.
• CHANGELOG.md untouched; branch/commit follow docs/gitflow.md.

Safe follow-ups enabled by this skill

• A read-only preflight job or scheduled report using scripts/platform-preflight.sh.
• An MCP readiness check in the example e2e (health endpoints only).
• A separate runtime warm pool for untrusted execution, leaving the DSH template unchanged.
• A combined DSH + sandboxd image only with an explicit maintenance/exec design and a documented trust boundary.