--- title: "Verified Code Deployment with Capsules" slug: "verified-code-deployment-capsules" summary: "A deployment pattern where code, instructions, checks, environment assumptions, and release decisions travel as a verifiable Capsule." status: "draft" version: "0.1" updated: "2026-05-07" audience: - "developers" - "platform teams" - "agent builders" tags: - "deployment" - "provenance" - "code" - "verification" - "agents" canonical_path: "/research/verified-code-deployment-capsules" --- # Verified Code Deployment with Capsules ## Code as a Tracked, Verifiable Work Artifact ### Abstract AI agents can write code, run checks, and prepare deployments. The missing artifact is not more code generation. It is a portable record that connects the generated code to intent, verification, deployment assumptions, and human approval. A deployment capsule packages the code artifact, build instructions, test results, environment constraints, provenance, and release handoff into a single verifiable record. The host still deploys to Cloud Run, Kubernetes, a VM, or another runtime. The capsule records what was built, what was verified, who or what approved it, and how another actor can continue or audit the work. --- ## 1. Problem Modern code deployment splits across many surfaces: - source repository - CI logs - package artifacts - deployment manifests - secrets manager - ticketing system - chat approvals - monitoring dashboards AI coding agents add another split: the reasoning behind changes often lives in a transient conversation. Once the code is committed, the model's assumptions, failed attempts, and verification path may disappear. A deployment capsule addresses the continuity gap. It does not replace CI/CD. It makes the deployment decision portable and auditable. --- ## 2. Deployment capsule anatomy A minimal deployment capsule can include: - `program.md`: release summary, risk, rollback notes, build/test/deploy plan, and next-actor continuation notes - `agents.md`: participants, roles, review authority, and trust notes - `manifest.json`: content index and skill trust metadata - `chain/events.jsonl`: append-only build/test/deploy events - `payload/artifacts/`: code bundles, patches, generated files, or checksums - `payload/checks/`: test reports, benchmark output, security scan summaries - `payload/deploy/`: Cloud Run service config, Kubernetes manifests, Terraform plan, or instructions - `skills/`: optional portable instructions for build, review, deploy, or rollback helpers - `provenance/envelope.json`: signed package metadata and verification boundary The capsule records deployment as a sequence of verifiable events: 1. code prepared 2. tests run 3. package hash recorded 4. human/agent approval granted 5. deployment command proposed 6. host executed deployment 7. runtime health checked 8. rollback or monitoring notes appended --- ## 3. What the capsule should not do A capsule should not hide credentials, impersonate an operator, or execute deployment by itself. The host supplies: - identity - credentials - network access - cloud project permissions - deployment runtime - actual command execution The capsule supplies: - intent - instructions - code artifacts or pointers - expected checks - event provenance - result envelopes This division keeps the protocol honest. The LLM is the runtime for reasoning. The host is the tool hand. The capsule is the ledger. --- ## 4. Cloud deployment bridge Google Cloud's current agent documentation frames managed agent runtime around deployment, access, tracing, logging, monitoring, sessions, memory, gateways, and secure code execution. ADK documentation also describes deployment paths to Cloud Run and Agent Runtime. A capsule can bridge local agent work to those runtimes. For example: - the capsule carries `deploy/cloud-run.md` and a checked service definition - the agent proposes deployment and records a `deployment_requested` event - an authorized host executes `gcloud run deploy` or an ADK deploy command - the host returns a structured `capsuleResult("deploy_cloud_run", {...})` - the capsule appends a Pith-compressed `deployment_completed` event with the exact machine envelope under `llm_return` The result is a deployment record that can move between agents and humans without losing the verification path. --- ## 5. Why this matters for AI-coded systems A code-generating model can produce a working artifact but still fail as a collaborator if it cannot transfer context. Capsules make the transferable unit explicit. For small projects, this can be as simple as a launchable HTML artifact capsule such as [capsules-extra/capsule-examples/public/hello-artifact](https://github.com/virionai/capsules-extra/tree/main/capsule-examples/public/hello-artifact). For production projects, it can evolve into a signed release capsule that carries checksums, deployment manifests, approval events, and rollback plans. This gives developers a better question than "did the model write code?" The better question is: "can another authorized actor verify what was written, why it was written, how it was tested, and how it was deployed?" --- ## 6. Recommended first reference implementation The first deploy-code capsule should be intentionally small. The working lab lives at [capsules-extra/capsule-examples/public/hello-artifact](https://github.com/virionai/capsules-extra/tree/main/capsule-examples/public/hello-artifact) and includes: 1. static web artifact or small API 2. local build script 3. deterministic test script 4. deployment instructions for Cloud Run 5. health check URL contract 6. rollback note 7. event chain recording build, test, deploy request, deploy result This is enough to prove the principle without confusing the capsule with a CI/CD system. --- ## Sources reviewed - Gemini Enterprise Agent Platform scale/runtime docs: https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale - ADK Cloud Run deployment docs: https://adk.dev/deploy/cloud-run/ - ADK Agent Runtime deployment docs: https://adk.dev/deploy/agent-runtime/deploy/ - Google Cloud IAM authentication docs: https://docs.cloud.google.com/iam/docs/authentication - Capsule hello artifact example: https://github.com/virionai/capsules-extra/tree/main/capsule-examples/public/hello-artifact