---
id: SAND-WP-0012
type: workplan
title: "Packer build orchestration"
domain: infotech
repo: sand-boxer
status: ready
owner: codex
topic_slug: custodian
created: "2026-06-24"
updated: "2026-06-24"
state_hub_workstream_id: "87838886-0f4a-4eae-8d0e-b464933089de"
---

# Packer build orchestration

Trigger Packer builds from `sandboxer create` and ship the-custodian
`make remote-build` shim — completing the build-machines migration arc.

Gap analysis P8: `history/2026-06-24-post-wp0007-intent-scope-gap-analysis.md`  
Carries forward: SAND-WP-0005-T06 (deferred)

**Predecessor:** SAND-WP-0011 (consumer profiles — proposed; attach mode done)  
**Follow-on:** reuse-surface federation publish; sandboxer01 operator track

---

## Packer build mode on ext.vm-packer

```task
id: SAND-WP-0012-T01
status: todo
priority: high
state_hub_task_id: "9dc30d94-1797-4c35-81a0-e75e5414f6fc"
```

Extend `VMPackerExtension` with optional `build` mode: inputs `packer_template`,
`vm_name` trigger local/SSH Packer run per the-custodian
`infra/build-machines/` conventions. Distinct from attach mode; teardown does not
destroy VM image. Tests mocked subprocess.

## profile.vm-packer-build

```task
id: SAND-WP-0012-T02
status: todo
priority: high
state_hub_task_id: "8e30794c-d8b9-48c7-ae93-db84724eedf2"
```

New profile binding build mode with placement and TTL suitable for long builds.
Document inputs in `docs/migration-build-machines.md`.

## Manager and CLI integration

```task
id: SAND-WP-0012-T03
status: todo
priority: high
state_hub_task_id: "685f766c-90ae-4698-87d0-b61535e7491a"
```

`create` path selects build vs attach via profile or `inputs.mode=build|attach`.
Progress events to State Hub during long provision. CLI help text.

## the-custodian remote-build shim

```task
id: SAND-WP-0012-T04
status: todo
priority: medium
state_hub_task_id: "6c4c0f85-5153-4fe9-84e6-26c5c9d33bb1"
```

In `the-custodian`: `make remote-build PROJECT=` delegates to
`sandboxer create --profile profile.vm-haskell-build` (attach) or new build
profile. Deprecation notice on legacy rsync-only path. Verification script
mirroring SAND-WP-0004 e2e shim pattern.

## Port-registry automation

```task
id: SAND-WP-0012-T05
status: todo
priority: low
state_hub_task_id: "701b2640-36ea-4702-b660-7169a4ec72cc"
```

Optional helper: register tunnel port from build-machines port-registry when VM
attach provisions (read-only or emit ops-bridge config snippet). Document only
if full automation deferred.

## Docs, tests, runbook

```task
id: SAND-WP-0012-T06
status: todo
priority: high
state_hub_task_id: "2378cd6a-ac23-47e9-a5d9-0d80b9e9f7af"
```

Update `docs/migration-build-machines.md`, `docs/extension-sdk.md`, operator
runbook under `docs/runbooks/`. `tests/test_vm_packer.py` build mode cases.
`make check` green.

---

## Out of scope

| Item | Track |
|------|-------|
| OVA import on hypervisor | Operator / build-machines |
| systemd build-agent changes | the-custodian infra |
| sandboxer01 host | Infra operator |

---

## Acceptance criteria

- Build mode provisions via CLI with mocked Packer in CI
- Attach mode unchanged (backward compatible)
- the-custodian shim documented and verified
- SAND-WP-0005-T06 superseded when complete