[pratikbin]

What

createos sandbox setup amp runs Amp's self-hosted orb provider on CreateOS. Each Amp thread gets its own sandbox: spawn creates or resumes it, pause keeps disk and memory, delete removes it.

export AMP_ORB_PROVIDER_TOKEN=$(cat ~/.config/amp/orb-provider-token)
createos sandbox setup amp --doctor
createos sandbox setup amp
amp -ox "your message" --orb-provider createos

End-user guide: docs/amp.md.

How it works

Same two-halves shape as setup orca:

• Human half: checks login, amp, and the token, writes a one-line wrapper to ~/.createos/amp-dispatch-<shape>-<template> (Amp takes a program path, not a command line; one file per setting so two providers never share one), then runs amp orb provider on it.
• Machine half (hidden --dispatch): run by Amp once per job, selected by ORB_OPERATION.

Problem found live	How it is handled
No GET-by-name, and the list holds every sandbox ever made (38k+ on one account), so resolveSandboxRef (200 newest) misses old paused orbs	Look up per live status (?status= filters server-side)
Sandbox names max 22 chars; ORB_ID is longer	amp- + 18 hex of sha256(ORB_ID)
Process env keys must be declared at create	Create with ORB_TOKEN="", AMP_URL=""
Templates only build FROM nodeops/sandbox:*, no COPY/ADD	Embedded amp-orb.Dockerfile rebuilds Amp's image contract with RUN; built on first use, devbox:1 + in-place setup as fallback
Pause and spawn for one orb can overlap; a spawn's setup woke a sandbox a pause had just stopped	Per-orb flock (released by the kernel even on SIGKILL)
Amp kills a job after 5 min	One 4m40s deadline for the whole job
ORB_TOKEN	Sent in a request body, never on a command line; debug logging off for that request
On devbox:1, /usr/local/bin/node links into /root (0700): root sees Node, the orb's user does not	Setup checks every tool as user
archive.ubuntu.com: 2 of 9 servers take 15–30 s per small file, turning a 4 s install into ~3 min	Ubuntu orbs use mirrors.edge.kernel.org (0.09 s steady), apt timeout 10 s, 3 retries

Testing

• Unit tests (7): naming, flag validation, the wrapper's exact argv (path with a space and a quote), one wrapper per setting, template rules, setup packages matching the Dockerfile, the lock.

• Live e2e (amp_e2e_test.go, build tag e2e, so go test ./... never creates sandboxes): builds the binary and drives it the way Amp does. 43/43 checks on 3 parallel runs (2 on the devbox:1 fallback, 1 on a ready template): every job, repeats, unreachable API, stale-bootstrap cleanup, AMP_URL, disk and memory across pause, spawn-during-pausing, pause-during-resuming, tools usable by user.

  CREATEOS_API_KEY=<key> go test -tags e2e -run TestAmpE2E -v -timeout 20m ./cmd/sandbox

• Real Amp thread in tmux, with a real provider token:

  Job	Result
  spawn (new)	81 s, orb connected, agent ran commands as user
  pause (thread archived)	29 s
  spawn (resume on new message)	13 s; agent: "Yes, Node works now: v18.19.1"
  delete (thread deleted)	2 s, sandbox destroyed

• golangci-lint 0 issues; builds for Windows (setup amp refuses there); gosec adds nothing new.

• govulncheck reports 19 Go stdlib issues for the pinned Go 1.26.3, identical on main. Not from this change; bumping Go is a separate fix.

Known issues / not in this PR

• Template builder fails every build right now (even FROM-only, ~0.7 s, empty log), so every orb boots devbox:1 and sets up in place. Reported to the control-plane owner with template id and request ids. Nothing needed here once it is fixed.
• One provider host. The lock is per machine; running the provider on several hosts needs a shared lock the API does not offer. Documented as an assumption.
• ORB_SNAPSHOT_ID is ignored (allowed by Amp's contract). No Desktop tab.
• Not observed: Amp's automatic idle pause (pause was triggered by archiving).

Mesh

Docs page Integrations/Amp.mdx added in createos-v2-landing (committed locally, not pushed). createos-plugin carries nothing for Amp.