Document custom training containers

[Eliza Farley (elizafarley)]

Note

The CLI change this PR documents is released. rdk #6566 and #6571 shipped in CLI v1.12.0 (released 2026-10-13), which replaces --container-version with --container-id. Users on v1.11.x or earlier still have the old flag.

Summary

Documents custom training containers: public Docker Hub images an org registers with Viam so custom training jobs run in a prebuilt environment instead of pip-installing heavy dependencies on billed GPU time.

• New page docs/train/custom-containers.md: what custom containers are, requirements, a security caution, how to build and push an image, register (CLI/Python) with the errors registration can return, list and delete containers, and limitations. For testing locally, submitting, and monitoring, it links to the existing sections on the custom training scripts page instead of repeating them. HTML comments mark where to add Web UI tabs for register, list, and delete once that UI exists.
• docs/train/custom-training-scripts.md (keeps the premium GPU billing sentence from Update custom training docs for premium GPU billing #5406): jobs run in a Viam-managed or custom container, --container-id in test-local and submit, the Container version dropdown lists both Viam-managed and custom containers, the Arguments step explains how arguments reach the script, test-local explains why to test locally and that it runs without a GPU, the API tab points to submit_custom_training_job with container_id, and the job details panel shows the container.
• docs/cli/reference.md: builds on the train containers list/register/delete sections that Update CLI reference for viam train containers register, delete and list --org-id #5397 added: links them to the new page, adds ID usage notes, and notes that deleting a container doesn't affect running jobs. New training-script test-local section. --container-id replaces --container-version in both submit custom tables and examples.
• docs/cli/datasets-and-training.md: --container-id throughout and a short "Manage training containers" section (register and delete commands) that links to the new page.
• docs/train/overview.md: card for the new page.

CLI versions

Every --container-id usage on train submit custom from-registry/with-upload and training-script test-local requires CLI v1.12.0. Register, delete, and list --org-id shipped in CLI v1.11.0.

Verified against code (2026-10-12, main)

• Permissions: only RoleOrganizationOwner has write_training_containers (viam-app auth/models/models.go), and it's checked for both register and delete. The docs say "organization owner". The scope doc said owner or operator, but the code doesn't match that.
• Registration errors: the documented messages come straight from viam-app mltraining/ml_training_service.go (Docker Hub only, must exist and be public, linux/amd64).
• UI: the dropdown label is Container version. Options read " (Viam)" or " (Custom: )". The job details Details panel shows Container version (description) and Container ID. Note that the handoff said "under Training script", but the code puts these in the Details panel.
• Hyperparameter tuning: custom containers aren't supported (APP-18108), but tuning is behind a feature flag and undocumented, so the docs don't mention it.
• Arguments: each key and value from the Arguments section reaches the script as --key=value (viam-app mltraining/vertex.go).
• Local testing: test-local runs docker run without --gpus, so local runs are CPU-only.
• Python SDK (v0.83.1): register_custom_training_container, list_containers, delete_custom_training_container, submit_custom_training_job(container_id=...). TypeScript and Go have no container support, so they aren't documented.

For reviewers

• The generated API reference (static/include/app/apis/generated/mltraining.md) lists description as optional for register_custom_training_container, following the SDK signature, but the server rejects an empty description (errNoDescriptionSpecified). The Python example passes description. A follow-up could fix the SDK docstring and default upstream.
• No public reference image exists, so the examples use docker.io/<your-username>/<image>:<tag> placeholders.

Jira

DOCS-4913 (epic), DOCS-5009, DOCS-4994, DOCS-5013, DOCS-5011, DOCS-5010, DOCS-5017, DOCS-5018. DOCS-5002 and DOCS-5005 are already covered by the generated Python API reference.

Test plan

• prettier@3.2.5, markdownlint-cli, and vale 3.12.0 (pinned) on the changed files: no errors
• python3 scripts/frontmatter_rules.py
• make build-prod
• New anchors resolve in the built HTML (#train-containers-register, #train-containers-delete, #training-script-test-local, API anchors)
• Spot-check the rendered pages in the deploy preview

🤖 Generated with Claude Code

[netlify]

✅ Deploy Preview for viam-docs ready!

Name	Link
🔨 Latest commit	5a7fd8d
🔍 Latest deploy log	https://app.netlify.com/projects/viam-docs/deploys/6acd318f90beaf83928f27b0
😎 Deploy Preview	https://deploy-preview-5407--viam-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 37 (🔴 down 1 from production) Accessibility: 100 (no change from production) Best Practices: 100 (no change from production) SEO: 92 (no change from production) PWA: 60 (no change from production) View the detailed breakdown and full score reports

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[github-actions]

🔎💬 Inkeep AI search and chat service is syncing content for source 'Viam Docs'