{"id": "TTC-120", "slug": "portable-and-self-hosted-ai-workflows", "title": "Portable and self-hosted AI workflows", "level": "advanced", "summary": "Portability comes from open, documented, versioned instructions and data; self-hosting adds operational control but also makes the operator responsible for security, updates, backups, recovery, and model limitations.", "learning_outcome": "Design and rehearse a provider-aware export, import, startup, and recovery workflow without embedding secrets or confusing the container with the portable agent.", "explanation": "Separate the portable agent contract from its runtime. Ordinary files can hold root instructions, structured rules, visible memory, sources, examples, corrections, and tests; a manifest records versions, checksums, dependencies, and excluded secrets. Containers can reproduce the classroom or service environment, but they are not the agent identity and do not guarantee identical model behavior across hardware or providers. A self-host operator must patch images, restrict listeners and egress, protect volumes and credentials, verify backups, monitor capacity, and rehearse restore. Export and import tests\u2014not a ZIP button alone\u2014prove practical portability.", "worked_example": "Fictional case: the Elm Archive exports AGENTS.md, YAML rules, approved memory, source metadata, examples, and tests with a manifest. A clean local project imports them and passes structural tests. Its Compose service binds to loopback, reads credentials from an excluded secret, restores a disposable volume backup, and records that responses may differ with another model.", "exercise": "Create a synthetic portable package manifest and a minimal self-host runbook. On a disposable directory, validate paths and checksums, import the package, run contract tests, start and stop the declared environment, restore test state from backup, and prove no credential entered the package.", "success_criteria": ["A clean environment can inspect and import every declared portable file with valid paths and checksums.", "Startup, health, stop/start persistence, backup, and scoped restore tests produce recorded results.", "Secrets and private runtime state are excluded, listeners and permissions are bounded, and model differences are disclosed."], "limitations": ["Self-hosting does not guarantee privacy, sovereignty, lower cost, availability, or model quality without verified operations.", "Container portability is constrained by architecture, accelerators, storage, network policy, licenses, and external dependencies."], "prerequisites": ["TTC-112", "TTC-113", "TTC-116", "TTC-119"], "next_lessons": ["TTC-117", "TTC-119"], "copyable_material": "# TTC-120 \u2014 Portable and self-hosted AI workflows\nObjective: Move an inspectable agent contract between supported environments and operate self-hosting with tested recovery.\nProcedure: Export ordinary files plus manifest; exclude secrets; validate and import cleanly; pin runtime dependencies; bind narrowly; test startup, persistence, backup, restore, and model variance.\nRequired evidence: Keep checksums, dependency versions, import tests, health results, backup receipt, restore proof, and known limitations.\nBoundaries: Docker is an environment, not the agent; portability does not grant publication, network, secret, or execution authority.\nCompletion test: A clean import passes contract tests and a disposable restore recovers intended state without secret leakage.\nReview rule: Treat generated work as a draft until the named human reviewer accepts it.", "sources": [{"title": "Open Container Initiative Image Format Specification", "publisher": "Open Container Initiative", "url": "https://specs.opencontainers.org/image-spec/"}, {"title": "Compose Specification", "publisher": "Compose Specification project", "url": "https://compose-spec.io/"}, {"title": "Custom instructions with AGENTS.md", "publisher": "OpenAI", "url": "https://developers.openai.com/codex/guides/agents-md/"}], "version": "1.0.0", "reviewed_on": "2026-10-03", "review_status": "reviewed", "next_review_criteria": "Package format, container specification, supported runtime, dependency, backup, or restore behavior changes.; A cited primary source is materially revised, replaced, or becomes unavailable.; Repeated learner results show that the exercise or success criteria are ambiguous.", "canonical_aliases": ["/agents-md/"], "canonical_url": "https://teachthecompany.com/school/portable-and-self-hosted-ai-workflows/"}