deepseek-kubernetes-sandbox/AGENTS.md

AGENTS.md

Guidance for AI coding agents (and humans) working in this repository. Read it before changing anything; it encodes the conventions the CI enforces.

What this repository is

• The root is the primary artifact. The Dockerfile packages DeepSeek Harness Web (dsh web) as a slim, non-root, multi-arch image. Everything else exists to support it or to demonstrate an implementation on top of it.
• Every implementation is a self-contained example under examples//. The multi-tenant platform lives in exactly one directory; do not split it into parallel examples.
• versions.env is the single source of truth for the DSH ref, pnpm, the control-plane versions and the image names.
• Docs describe the shipped behavior, not intentions. If you change a manifest, port, env var or workflow, update the docs in the same change.
• CHANGELOG.md is generated by git-cliff from Conventional Commits. Never edit it by hand.

Golden rules

1. Keep the Dockerfile working for both linux/amd64 and linux/arm64; it must stay the first-class artifact.
2. Never hard-code a version, image tag or registry path. Edit versions.env and run make set-version when bumping.
3. Never commit a real secret or usable credential. Secret-shaped YAML lives in *.yaml.example files; keys are documented in .env.sample only.
4. Every manifest under examples//manifests/ must parse and pass a server-side dry-run in CI. Keep manifests numbered (NN-.yaml), and keep exposure variants under manifests/exposure// documented by the single manifests/exposure/README.md (variants are mutually exclusive).
5. Do not edit CHANGELOG.md, and do not move or delete published tags. Releasing is documented in docs/versioning.md.
6. Keep the gateway HTTP/WebSocket contract stable unless the change is explicitly about it; clients and examples depend on it.

Repository map

Path	What lives there
Dockerfile	Main DSH Web image (build + runtime stages, entrypoint)
versions.env	Every pinned version and image name
Makefile	Canonical local entrypoint
build.sh	Deprecated shim that forwards to make
docs/	main-image.md, examples.md, gitflow.md, versioning.md (index: README.md)
examples/	One implementation per directory (contract in docs/examples.md)
examples/dsh-agents-as-a-service/	The multi-tenant platform example (manifests, gateway, docs, scripts)
examples/minimal-single-tenant/	The just-one-DSH-Web quickstart
scripts/	check-versions.sh, check-examples.sh, check-manifests.py, set-version.sh
.dsh/skills/	Project-local DSH skills (auto-discovered); dsh-agent-sandbox-platform covers platform operation, MCP limits and extension recipes
.github/workflows/	ci.yaml (lint, dependency-review), ci-python.yaml, ci-manifests.yaml, ci-image.yaml (amd64 build + smoke test on Dockerfile/versions.env changes), reusable _build-image.yaml, build-*, release.yaml, e2e-kind.yaml, pr-title.yaml, codeql.yml

Commands

make check        # versions, example layout and manifest YAML (run before every commit)
make test         # gateway unit tests (pytest)
make lint         # ruff + shellcheck (+ yamllint/actionlint when installed)
make image        # build the main DSH Web image (slow: clones and builds DSH)
make gateway      # build the example gateway image (fast)
make e2e          # full kind walkthrough; needs a cluster with agent-sandbox
make changelog    # regenerate CHANGELOG.md with git-cliff (release only)
make release-dry-run
make set-version DSH_VERSION=dsh-vX.Y.Z RELEASE_REVISION=rN

No cluster is needed for check, test, lint, gateway or image. Only make e2e needs kind plus the agent-sandbox CRDs (see the example README).

Testing expectations per change

Change	Minimum verification
Documentation only	make check; verify relative links
Example manifest	make check; kubectl apply --dry-run=server in CI
Optional hardening (gVisor, nodeSelector, NetworkPolicy, provider keys, failed-Pod recovery)	make check; server dry-run in CI; manual verification on a capable cluster
Gateway code	make test; make lint; add or update tests
Dockerfile / versions.env	make check; the CI build-amd64 job (ci-image.yaml) builds and smoke-tests the image on the PR; run make image locally only when you need the image
Workflow	actionlint in CI; keep actions SHA-pinned; no hard-coded versions
New example	make check; all files described in docs/examples.md
Project skill (.dsh/skills/)	make check; validate frontmatter; keep SKILL.md under ~8 KB; shellcheck skill scripts; load it with the skill tool

Versioning and releases

• Release identity = DSH_VERSION plus an optional -rN repository revision. The current identity is dsh-v0.2.1-rc.5-r6 (first release at this DSH ref, so no suffix); a repository-only change at the same ref publishes -r2.
• Channels: release tags are immutable; latest follows the newest release; main is the development channel for both image packages.
• A broken release is fixed by publishing -r(N+1), never by re-tagging.
• The full procedure, compatibility table and rollback rules are in docs/versioning.md.

Branch and PR conventions

• Trunk-based with release branches, documented in docs/gitflow.md.
• Branch names: feat/, fix/, docs/, chore/, refactor/, test/.
• Conventional Commit subjects and PR titles (feat(scope): ..., fix(scope): ...).
• PRs are squash-merged; main stays linear and protected.
• Required on every PR: lint, pr-title, CodeQL (both Analyze jobs) and dependency-review. python, manifests and build-amd64 are path-filtered on-demand checks; run them when the change touches their scope.
• Keep diffs scoped; update docs with the code; never mix a version bump with unrelated changes.

Adding an example

1. Read docs/examples.md and examples/README.md.
2. Create examples// with README.md, manifests/NN-*.yaml, optional manifests/optional// or manifests/exposure// (each with a README), optional components with their own Dockerfile/README/tests, and scripts/ (executable, idempotent, self-cleaning).
3. Publish component images under ////.
4. Add the example to examples/README.md; scripts/check-examples.sh enforces the layout.

Security notes

• AUTH_PROXY_HEADER is opt-in. Only enable it when the gateway Service is reachable exclusively through the authenticating proxy; otherwise any client can spoof X-Forwarded-User. The SSO variant's NetworkPolicy is required for production, and examples/dsh-agents-as-a-service/scripts/preflight-sso.sh verifies the setup (Secrets, gateway env, TLS reference, placeholders, second paths).
• The example gateway reads the DSH launch token from pod logs. Treat pod logs as sensitive and keep its RBAC namespace-scoped.
• Browser sessions are opaque server-side ids held in gateway memory: they are revocable (logout/delete/recreate/expiry) but a gateway restart logs everyone out and horizontal scaling needs a shared store. Session cookies are never accepted as bearer tokens.
• AUTH_RATE_LIMIT, SIGNUP_INVITE_CODE, MAX_IN_FLIGHT_PER_USER and WS_MAX_MESSAGE_BYTES are in-process abuse guards, not ingress rate limits, quotas or an audit log. Add those for an internet-facing deployment.
• The example shares provider keys (dsh-provider-keys plus the optional dsh-provider-keys-extra) across sandboxes; do not describe it as tenant-isolated.
• gVisor, nodeSelector, the shipped sandbox/exposure NetworkPolicies and the documented gateway egress policy, extra provider keys and failed-Pod recovery are opt-in and are not active in the base manifests; do not describe the base example as hardened. The sandbox and gateway-egress policies are required production steps; an exposure without its NetworkPolicy is demo-only. See the example's production checklist.
• TLS terminates outside the gateway. Set COOKIE_SECURE=true for HTTPS and drop ALLOW_INSECURE_COOKIES; the gateway refuses COOKIE_SECURE=false unless ALLOW_INSECURE_COOKIES=1, which is only for the plain-HTTP local demo. Never expose that combination.

Ask before

• Changing release workflows, tag formats or published image names.
• Editing the gateway's public routes or auth semantics.
• Adding a new top-level tool, service or dependency to the main image.
• Rewriting generated files (CHANGELOG.md) or git history.

Where to look first

• docs/main-image.md - container contract and tags
• docs/examples.md - example authoring rules
• docs/gitflow.md - branches, PRs, required checks
• docs/versioning.md - versioning, changelog, releases
• .dsh/skills/dsh-agent-sandbox-platform/SKILL.md - platform operations, MCP limits, extension recipes
• CONTRIBUTING.md - development setup
• SECURITY.md - vulnerability reporting and threat notes