feat: support -i background queue on cloud providers

[madarco]

What

The -i / --initial-prompt background queue was docker-only: agentbox claude -i "<prompt>" (and codex / opencode) on a cloud provider was hard-rejected with "-i / --initial-prompt is currently docker-only (cloud sessions only start on attach)."

That rejection was a v1 scoping shortcut, not a real limitation. The mechanism to seed a prompt without an interactive attach already shipped: provider.buildAttach(box, 'agent', { command, detached: true }) creates + configures the agent's tmux session running the full launch command without attaching (already used for new-tab attach pre-starts). This PR wires the queue worker to use it, so cloud -i reaches parity with docker.

Changes

• Remove the cloud rejection in the -i branch of claude.ts / codex.ts / opencode.ts (the provider-neutral credential pre-check stays).
• Extract cloudAgentStartDetached (+ shared startDetachedSession) in _cloud-attach.ts; refactor the existing new-tab pre-start call site to reuse it (one implementation).
• Route the queue worker on job.providerName in _run-queued-job.ts: docker keeps runDockerJob; cloud gets runCloudJob, mirroring the foreground cloud-create path (provider.create does credential volumes / git-bundle seed / ctl daemon) and pre-starting the prompt-seeded session detached.
• Seed prompt + post--- args (e.g. --permission-mode=plan) forward through buildPromptArgs → the cloud launcher unchanged.
• Docs: updated skills/agentbox/SKILL.md (cross-provider + arg-forwarding example); added a unit test for the prompt+args → launcher contract.

The concurrency gate and queue list UX already work cross-provider — no queue-loop changes.

Verification

• pnpm build / typecheck / lint clean; full suite 368 tests pass (cloud-attach +1).
• Live on Vercel (--provider vercel):
  • Parallel cloud -i jobs → two boxes, both done.
  • Autonomous run actually does work: a non-plan-mode job created QUEUE_TEST.md with the exact requested content (verified via sbx exec).
  • Custom args forwarded: -- --permission-mode=plan → claude launched in plan mode.
  • Status events flow from cloud queued boxes (claude:waiting / claude:idle) — the input the working-agent gate consumes.
  • Interactive: sending 1+Enter to the pre-started session's plan prompt advanced claude (approved → executed → switched to auto mode), proving the queue-pre-started detached session is a fully-functional interactive session.

Notes (pre-existing, not introduced here)

• --max-running (running-box gate) can over-start when box-create lags the scheduler tick: defaultCountRunningBoxes reads state.json and doesn't count in-flight queue jobs whose box isn't created yet. Affects docker identically; the working-agent gate (--max-working) is the one that counts in-flight creates. Tracked separately.
• agentbox <agent> attach defaults to a new-terminal split; use --inline to attach in the current terminal.

---

Note

Medium Risk
Adds a new cloud create + detached-session path in the hidden queue worker; failures may leave boxes without a usable session until attach, but reuses existing attach/detached plumbing rather than new auth or data handling.

Overview
-i / --initial-prompt background queue now works on cloud providers (Daytona, Hetzner, Vercel), not only Docker. The CLI no longer rejects cloud when -i is set on agentbox claude, codex, or opencode.

The internal queue worker (_run-queued-job) branches on job.providerName: Docker keeps baking the prompt into tmux new-session; cloud runs runCloudJob (create box via provider.create, then cloudAgentStartDetached) so a detached tmux session is seeded before any attach—reusing the same buildAttach({ detached: true }) path already used for new-tab attach pre-starts. startDetachedSession is shared between that path and the queue worker.

Docs (skills/agentbox/SKILL.md) and a unit test on buildPromptArgs → buildCloudAttachInnerCommand document that the seed prompt and post--- args reach the in-box agent in order.

^{Reviewed by Cursor Bugbot for commit f081fbf. Configure here.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agentbox-web	Ready	Preview, Comment	May 31, 2026 12:53pm