@boxes-dev/dvb-runtime 1.0.1079 → 1.0.1081

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -22,7 +22,7 @@ than separate agent choices.
22
22
 
23
23
  Start threads from the desktop thread list.
24
24
 
25
- Use **New devbox + thread** for most work. A devbox thread gives the task its
25
+ Use **New thread** for most work. A devbox thread gives the task its
26
26
  own isolated machine. In an ordinary project, this uses the latest Template-box
27
27
  snapshot when one is available. In a Team Template member project, it uses the
28
28
  Team Template's current saved version and the project's prepared devbox pool.
@@ -241,6 +241,10 @@ start selected under **Add to**; a pasted Codex or Claude setup command selects
241
241
  only its agent. Adjust the selection, then choose **Add MCP** to save and
242
242
  authorize the connection.
243
243
 
244
+ The mobile app manages the same list under a project's **Project settings →
245
+ MCPs**, including adding connections and signing in for each agent on the
246
+ phone. See `mobile.md`.
247
+
244
248
  Codex and Claude are enabled independently from the same connection row. OAuth
245
249
  opens a local browser sign-in for the selected agent, so enabling both agents
246
250
  usually requires one provider consent for Codex and another for Claude. API-key
@@ -252,12 +256,28 @@ Template box and devbox, including future and sleeping machines, without a
252
256
  snapshot. A project-scoped connection can use a different account from a
253
257
  connection in another project.
254
258
 
259
+ Without the desktop app, open **MCPs** in the header of the boxes.dev website
260
+ from any browser. Choose a project; the page offers the same
261
+ list, **Add MCP**, agent chips, and row menus, but not **Template-managed
262
+ MCPs**. To sign in to an OAuth MCP there, choose **Open sign-in page** in the
263
+ sign-in dialog and approve access in the new tab. The provider will then send
264
+ that tab to an address starting with `http://127.0.0.1:` that can't load. Copy
265
+ that tab's full address, paste it into the dialog, and choose **Finish
266
+ sign-in**. Each sign-in needs to be finished within 10 minutes, and its address
267
+ works only once. The dialog also shows the `dvb mcp authorize` command for
268
+ people who prefer to sign in from a terminal on their own computer. An MCP that
269
+ only a private network can reach can't be signed in from the website; use the
270
+ desktop app or `dvb mcp authorize` for it. Sign-in links opened from a Template
271
+ box or devbox, for example after `codex mcp add`, will open this page in a
272
+ normal browser with that connection's sign-in ready.
273
+
255
274
  Supported remote HTTP commands are another entry point to the same list. Running
256
275
  a command such as `codex mcp add <name> --url <url>` or `claude mcp add
257
276
  --transport http <name> <url>` in a Template box or devbox creates the central
258
- current-project connection and continues authorization through the desktop app
259
- or the shown local-computer instructions. It does not create a separate
260
- machine-only copy. To enable both agents, run each agent's setup command with
277
+ current-project connection. It does not create a separate machine-only copy.
278
+ When the server uses OAuth, the command will try to open sign-in in your
279
+ browser and will print a `dvb mcp authorize` command. If the browser doesn't
280
+ open, run that command in a terminal on your own computer, not on the box. To enable both agents, run each agent's setup command with
261
281
  the same name, URL, and authentication details, including any API-key headers.
262
282
  The second command will add its agent to the existing project connection;
263
283
  repeating either command will keep the existing connection and sign-in. OAuth
@@ -576,11 +596,16 @@ steer at its next available opportunity; a message sent during a final response
576
596
  may get a separate response afterward. Both actions support Claude's existing
577
597
  attachments.
578
598
 
579
- Desktop Settings has a separate **Claude replies** default. Enter will use
580
- that action while Claude is working, and Cmd/Ctrl+Enter will use the alternate
581
- action. On mobile, use the **Queue**/**Steer** control beside the composer.
582
- An idle thread starts normally with either preference. Once Claude accepts a
583
- steer, it cannot be edited or deleted as a waiting Queue message.
599
+ On desktop, Enter and the send button will Steer while Claude is working, and
600
+ Cmd+Enter (Ctrl+Enter on Windows and Linux) will Queue the message instead. The
601
+ send button's tooltip shows both shortcuts. Slash commands always wait for the
602
+ current response. On mobile, use the **Queue**/**Steer** control beside the
603
+ composer. An idle thread starts normally either way. Once Claude accepts a
604
+ steer, it cannot be edited or deleted as a waiting Queue message. If a thread
605
+ can't accept a steer, such as while Claude waits for an answer to its question,
606
+ the message will show **Message send failed** instead of being queued.
607
+ **Edit message** will return it to the composer and show the reason; then queue
608
+ it or wait for Claude to finish.
584
609
 
585
610
  The desktop and mobile composers also stay available while Codex or Claude
586
611
  Code is starting, reconnecting, or preparing a new fork. On desktop, sending to
@@ -661,12 +686,17 @@ Codex threads expose model controls in the composer footer:
661
686
  Ultrafast when the model offers it. Fast and Ultrafast are labeled as faster
662
687
  with increased usage.
663
688
 
664
- On desktop, type `$` in a Codex reply box to choose from the skills available
665
- to Codex on that machine. Each row shows whether the skill comes from the
666
- project, your personal skills, or Codex itself. Choosing a skill inserts a
667
- `$name` link to its `SKILL.md`, and Codex will load that skill's instructions
668
- with the message. A machine with an older boxes.dev service won't show the
669
- list until its normal automatic update runs.
689
+ On desktop or mobile, type `$` in a Codex reply box to choose from the skills
690
+ available to Codex on that machine. Each row shows where the skill comes from:
691
+ Project, Personal, Plugin, Account (a plugin installed through your ChatGPT
692
+ account or workspace), Admin, or Built-in. Choosing a skill inserts a `$name`
693
+ link to its `SKILL.md`, and Codex will load that skill's instructions with the
694
+ message. A new thread on mobile, or a desktop **New devbox + thread** draft,
695
+ shows the skills boxes.dev last read from a Codex thread in the same project,
696
+ so its list fills in once a started Codex thread in that project has been
697
+ opened; Account skills appear there only while the Codex account they came from
698
+ is selected. A machine with an older boxes.dev service won't show the list
699
+ until its normal automatic update runs.
670
700
 
671
701
  Codex also shows context-window usage when available. When the context window
672
702
  gets full, the composer can show an auto-compaction warning and a Compact now
@@ -696,16 +726,18 @@ patches, background work, or connected-app calls remain separate. These rows
696
726
  remain stable after navigating away, loading older messages, or reloading the
697
727
  thread. Redundant code-step bookkeeping is omitted once later activity proves
698
728
  it was superseded, while genuine waits and interrupted work remain visible.
699
- Images that Codex explicitly emits for the user stay visible outside folded
700
- Working activity, including after navigating away, reloading, or loading older
701
- history. Older activity captured before this metadata was available can still
729
+ Older activity captured before this metadata was available can still
702
730
  show a generic code-call row; boxes.dev does not guess or reconstruct tool
703
731
  calls that were not recorded at runtime.
704
732
 
705
733
  Desktop transcript history collapses the intermediate activity of older
706
734
  completed Codex turns. The newest turn shows its available activity while
707
735
  Codex works and after it finishes. Collapsing activity keeps your messages
708
- visible in their original order.
736
+ visible in their original order. Images that Codex displays through its tools
737
+ appear in order while the turn runs and fold with the rest of its activity;
738
+ expanding the activity shows them in their original place. To keep images or
739
+ videos in view, Codex presents them as a gallery in its final reply (see
740
+ `onbox-agent-tools.md`).
709
741
 
710
742
  Codex activity initially loads its most recent portion. In a gap, use
711
743
  **↓ Load next** to load forward from its beginning, or **Load previous ↑**
@@ -752,8 +784,15 @@ remain visible after returning to or reloading the thread until resolved.
752
784
 
753
785
  Claude threads expose model and reasoning controls when available. Claude also
754
786
  supports slash commands when the thread surface has command lookup
755
- enabled. On desktop, `/model` opens the model picker, and `/model <model>`
756
- switches directly to a known model. Older supported model generations appear
787
+ enabled. Type `/` in a Claude reply box on desktop or mobile to list Claude's
788
+ commands and skills; choosing one adds it to the message. Skill rows show
789
+ Project, Personal, Plugin, or Account (skills synced from the claude.ai
790
+ account). A new thread on mobile, or a desktop **New devbox + thread** draft,
791
+ uses the project's most recently opened Claude thread for project and personal
792
+ skills, and the selected Claude account's last list for its synced skills and
793
+ Claude's built-in commands, which depend on the account's plan. On mobile, the
794
+ list leaves out `/model` and `/fast`, which the model menu covers. On desktop, `/model` opens the model picker, and
795
+ `/model <model>` switches directly to a known model. Older supported model generations appear
757
796
  under **More models** in the picker.
758
797
 
759
798
  Fast mode runs Claude faster at a higher usage rate on models that support it,
@@ -769,6 +808,22 @@ the account uses a setup token, the organization has turned it off, or a fast
769
808
  mode rate limit is in effect, the menu shows the reason and Claude runs at
770
809
  standard speed.
771
810
 
811
+ **Ultracode** is available in the desktop **Reasoning** menu and the mobile
812
+ model options for supported Claude threads. Claude will use workflows to run
813
+ large tasks in parallel at a much higher usage rate.
814
+ Reasoning effort stays separate; Ultracode can run at Low. The choice belongs
815
+ to that thread and survives reopening or switching devices. It does not
816
+ become the last-used default for new drafts. A thread with no explicit choice
817
+ follows Claude settings, where Ultracode is off unless the user enabled it.
818
+
819
+ When selected, the reasoning control shows **Ultracode** while it is active
820
+ or requested for a draft. If Claude reports it unavailable, the choice stays
821
+ selected, the menu explains the limitation, and the thread continues normally
822
+ without Ultracode. Availability depends on the model, Claude configuration,
823
+ and account; a draft's model eligibility cannot guarantee availability before
824
+ Claude starts. Older runtimes may omit the control. Changing effort preserves
825
+ the Ultracode choice.
826
+
772
827
  An idle Claude chat can continue in a separate chat. Use exact `/fork` to
773
828
  continue from the current tip on the current Template box or devbox. Or use the
774
829
  Split icon beneath a completed desktop response to keep history only through
@@ -834,6 +889,11 @@ Claude Code can also coordinate several agents as a Workflow. Its transcript
834
889
  card shows the delegated summary and lifecycle, plus phase and agent progress
835
890
  when Claude provides it. Expanding the card shows that progress without
836
891
  exposing the generated workflow script or internal task identifiers.
892
+ The owner can choose **Stop** on a running Workflow card to stop only that
893
+ workflow; other workflows keep running. The composer's **Stop** ends the
894
+ current response and all running workflows in the thread. Workflow work
895
+ survives closing the thread or sending a follow-up, and its card remains the
896
+ place to stop it after the launching response.
837
897
 
838
898
  Native Claude Code transcripts do not expire after 30 days on managed Template
839
899
  boxes and devboxes. They remain on the owning machine until boxes.dev
@@ -872,8 +932,10 @@ On desktop, boxes.dev folds intermediate activity for an older Claude Code turn
872
932
  after the user prompt and final agent reply are both available. The current
873
933
  turn continues to show its available commentary and tool activity inline. A
874
934
  stopped or failed turn without a final agent reply also stays expanded. Images
875
- returned successfully by Claude Code tools stay visible outside the collapsed
876
- activity, before the final agent reply.
935
+ returned by Claude Code tools fold with the rest of that activity and appear in
936
+ their original place when it is expanded. A turn with no other folded activity
937
+ keeps its tool images inline. To keep images or videos in view, Claude presents
938
+ them as a gallery in its final reply (see `onbox-agent-tools.md`).
877
939
 
878
940
  ## GUI And CLI Views
879
941
 
@@ -1042,9 +1104,11 @@ confirm first.
1042
1104
  A share link is the invitation link. It works only for signed-in people who are
1043
1105
  currently on the owner's boxes.dev team. Opening it successfully grants access
1044
1106
  through that exact active share and adds the thread to the viewer's
1045
- **Shared with me** section on desktop and mobile. The thread's permanent
1046
- `/thread/` link is different: it identifies the thread for Team work, Git
1047
- history, and the CLI, but does not grant access or save the thread by itself.
1107
+ **Shared with me** list. On desktop, open **Project → Shared with me** for
1108
+ saved teammate conversations across projects; mobile keeps its Shared with me
1109
+ section. The thread's permanent `/thread/` link is different: it identifies
1110
+ the thread for Team work, Git history, and the CLI, but does not grant access
1111
+ or save the thread by itself.
1048
1112
  It always applies the current team policy, privacy setting, and share access.
1049
1113
  On a shared-thread browser page, choose **Open in app** to open the same
1050
1114
  read-only thread in the desktop app, or in the mobile app when viewed on a
@@ -1060,10 +1124,11 @@ that has permission to read other threads. Read and unread state is personal
1060
1124
  to each viewer and does not change the owner's state.
1061
1125
 
1062
1126
  Under **Thread titles**, a teammate can choose **Request access**. On desktop,
1063
- the project sidebar's **Shared by me** section appears whenever the selected
1127
+ the sidebar's **Project → Shared by me** row appears whenever the selected
1064
1128
  project has an active share or a pending access request. Shared threads are
1065
- listed with copy-link and revoke controls, pending requests appear above them
1066
- with accept and dismiss controls, and selecting any row opens that thread.
1129
+ listed beneath the expandable row with copy-link and revoke controls; pending
1130
+ requests appear above them with accept and dismiss controls, and selecting any
1131
+ row opens that thread.
1067
1132
  Owners can also review requests on mobile. Accepting a request will make the
1068
1133
  current share link available to that requester in boxes.dev; the requester
1069
1134
  opens it to complete access and add the thread to **Shared with me**. Requests
@@ -1092,12 +1157,12 @@ snapshot. A missing file shows **File not found**; a destroyed or unreachable
1092
1157
  source shows **Image unavailable**. Other local file links do not grant
1093
1158
  workspace access.
1094
1159
 
1095
- Teammates who can read a thread also see the interactive visuals that the
1096
- owner's agents published in its replies, without starting the source devbox.
1097
- A visual's link opened on its own works for the owner and for people who can
1098
- currently read the thread where it was published. Copying the link into a
1099
- teammate's thread, another conversation, or Slack does not give anyone else
1100
- access.
1160
+ Teammates who can read a thread also see the interactive visuals, images, and
1161
+ videos that the owner's agents published in its replies, without starting the
1162
+ source devbox. A published link opened on its own works for the owner and for
1163
+ people who can currently read the thread where it was published. Copying the
1164
+ link into a teammate's thread, another conversation, or Slack does not give
1165
+ anyone else access.
1101
1166
 
1102
1167
  ## Thread Actions
1103
1168
 
@@ -70,6 +70,36 @@ runaway processes. boxes.dev reserves some resources for control, so this works
70
70
  even when agent or user processes are stuck. If it still does not recover, use
71
71
  **Machine > Reset**, then **Machine > Reboot** only if Reset fails.
72
72
 
73
+ ## A Build Or Command Was Terminated
74
+
75
+ When memory runs low, the boxes.dev memory watchdog may stop a large workload
76
+ process, such as a build or test runner, to keep the machine responsive.
77
+ If a command unexpectedly reports `Terminated` or `Killed`, read this file on
78
+ the affected devbox or Template box:
79
+
80
+ ```bash
81
+ cat /run/boxes-memory-terminations.jsonl
82
+ ```
83
+
84
+ The file keeps the latest 20 signals sent by the watchdog, one JSON record per
85
+ line, oldest first. Compare `at` (UTC time), the process name, and `pid` (if you
86
+ know it) with the failed command.
87
+ `comm` is the short process name, and `rssBytes` is its memory use when selected.
88
+ The remaining memory figures describe pressure when the signal was sent.
89
+ Command arguments are omitted. `TERM` asks the process to stop; `KILL` means
90
+ the watchdog sent a force-stop signal after its grace period while pressure
91
+ continued. A record confirms that a signal was sent, not the process's exit
92
+ status.
93
+
94
+ Reduce build/test parallelism or stop unnecessary workloads before retrying.
95
+ Use the desktop CPU or memory meter to inspect current usage. The file is
96
+ cleared on reboot; a restored snapshot can include older records, so check the
97
+ timestamps. Older machines may need a boxes.dev update before it is available.
98
+ A missing or unmatched record does not rule out memory exhaustion:
99
+ kernel out-of-memory kills are separate and are not recorded here. If the cause
100
+ is still unclear, keep the command output and approximate failure time for
101
+ support.
102
+
73
103
  ## Setup Upload Or Remote Setup Paused
74
104
 
75
105
  If a large encrypted bundle upload is interrupted, boxes.dev will first
@@ -174,6 +204,11 @@ directly there are under **Template-managed MCPs** in the same place. Team
174
204
  Template member projects omit that inventory. If sign-in fails, follow the
175
205
  recovery message on that MCP's card.
176
206
 
207
+ Without the desktop app, use **MCPs** on the boxes.dev website instead. If
208
+ **Finish sign-in** says the address isn't from this sign-in, paste the full
209
+ address from the tab you opened for that sign-in. If the sign-in expired or
210
+ the provider declined it, start signing in again from the agent chip.
211
+
177
212
  When you send to an existing Claude thread in the desktop app, a slow MCP
178
213
  reconnection can delay the message while Claude gets ready. boxes.dev will
179
214
  keep the message queued and continue automatically when preparation finishes,
@@ -190,10 +225,14 @@ that sign-in finished. Choose **Retry status check** on the row (or
190
225
  **Refresh**) to keep checking the same sign-in, or **Cancel** to stop it and
191
226
  start over.
192
227
 
193
- Older desktop app versions may provide a `dvb mcp authorize` command instead of
194
- opening sign-in. Run that command in a terminal on your own computer, never in
195
- a Template box or devbox. Installing or running the workstation `dvb` CLI
196
- inside a managed machine can break the environment.
228
+ To sign in from a terminal instead (on Linux, Windows, or over SSH), run
229
+ `dvb mcp authorize <connection> --agent codex` or `--agent claude` on your
230
+ own computer. An MCP command run on a box prints the exact
231
+ command to use. Never run it in a Template box or devbox: installing or running
232
+ the workstation `dvb` CLI inside a managed machine can break the environment.
233
+ If the browser is on another computer, it will end on a `http://127.0.0.1:...`
234
+ page that doesn't load after you approve access. Paste that page's full address
235
+ into the terminal to finish signing in.
197
236
 
198
237
  If a selected thread shows an inline auth refresh action, use that action
199
238
  first.
@@ -383,9 +422,11 @@ the App lacks the permission that command needs. Repeat a `gh api` request with
383
422
  `-i` to see the `X-Accepted-GitHub-Permissions` response header, which names the
384
423
  missing permission, such as `actions=write` or `issues=write`.
385
424
 
386
- Supported commands will show a direct permission-review link when the targeted
387
- installation needs a newly requested grant. Give the user that link and ask an
388
- installation owner to accept the update, then retry the command. Email reads
425
+ Supported commands will show a direct permission-review link before they run
426
+ when the targeted installation lacks a newly requested grant. If GitHub denies
427
+ the command, give the user that link and ask an installation owner to accept
428
+ the update, then retry the command. If the command succeeded, it didn't need
429
+ the update, so don't run it again. Email reads
389
430
  will link to Account's **Update connection** because each user must authorize
390
431
  that account permission. If no link appears, use the steps below. Unavailable
391
432
  metadata and an unknown account with mixed installation grants won't produce
@@ -0,0 +1,108 @@
1
+ # Unattended work
2
+
3
+ An agent can save a later check in its current thread or keep its current box
4
+ awake for bounded local work. Both Codex and Claude use the same commands.
5
+ The saved purpose and time appear above the composer and in the thread list;
6
+ the box's power menu shows its active requests. A timer is separate from the
7
+ agent's Working status.
8
+
9
+ ## Schedule a check
10
+
11
+ For a delayed status inspection, save one prompt in the current thread:
12
+
13
+ ```sh
14
+ dvb-onbox threads schedule set --after 10m \
15
+ --reason 'Check deployment status' --prompt-file /tmp/deployment-check.txt \
16
+ --idempotency-key deployment-check-1 --json
17
+ dvb-onbox threads schedule get --json
18
+ dvb-onbox threads schedule cancel --id <check-id> --json
19
+ ```
20
+
21
+ Use `--at` with an ISO timestamp and explicit timezone instead of `--after`
22
+ for a clock time. Duration values use `s`, `m` or `h`. A check must be one
23
+ minute to 24 hours ahead. Reasons are limited to 120 characters; prompt files
24
+ are limited to 32 KiB. The agent should finish its current reply after saving
25
+ the check so the thread can become idle.
26
+
27
+ At the saved time, boxes.dev will wake the box if needed and try to start the
28
+ prompt in this thread. It will wait behind active work, unanswered questions
29
+ and pending user messages, for up to 30 minutes after the requested time.
30
+ The window bounds new attempts; ordinary waking and starting can take longer.
31
+ Existing account, usage and capacity limits still apply.
32
+
33
+ Each thread can have one pending check. A new `set` replaces that slot and
34
+ returns the replaced request. Repeating the same key and arguments returns
35
+ the original result and deadline; changed arguments need a new key.
36
+ Cancellation takes the request's ID so it cannot cancel a newer replacement.
37
+ Once a check is starting, cancellation cannot retract it; inspect the thread
38
+ and use Stop if needed. A confirmed start means the agent received the
39
+ prompt, not that the requested work finished.
40
+
41
+ If the check misses its window or fails, an attention notice remains until
42
+ dismissed. Uncertain delivery requires inspecting the thread; do not resend
43
+ an operation that might already have run. Existing Claude-native alarms
44
+ appear read-only and must be managed through their native controls before
45
+ setting another check.
46
+
47
+ ## Keep local work awake
48
+
49
+ Use a hold only when sleeping would prevent necessary local work:
50
+
51
+ ```sh
52
+ dvb-onbox devboxes keep-awake set --for 20m \
53
+ --reason 'Wait for the local integration test' \
54
+ --idempotency-key integration-test-1 --json
55
+ dvb-onbox devboxes keep-awake get --json
56
+ dvb-onbox devboxes keep-awake cancel --id <request-id> --json
57
+ ```
58
+
59
+ Each thread can have one active request. Omitting `--for` uses 20 minutes;
60
+ the allowed interval is one minute to four hours. Reasons are limited to
61
+ 120 characters. `set` replaces this thread's request, and same-key replay
62
+ keeps its original deadline. Cancel with the returned request ID when the
63
+ work finishes. A hold keeps the box and its agent available; it does not
64
+ launch, supervise or restart a command.
65
+
66
+ An awake box uses box-hours even while waiting, and agent responses may use
67
+ model allowance. The response estimates box-hours for the requested interval
68
+ at the current box size. It is not an additional charge or a total spending
69
+ cap. Multiple requests on one box do not multiply the box's billing rate.
70
+ Each request is bounded separately; agents must not silently chain requests
71
+ beyond the user's agreed monitoring period.
72
+
73
+ Expiry or cancellation releases that request's protection without killing
74
+ commands or interrupting a foreground response. Other requests, background
75
+ work or the normal idle grace may keep the box awake. Expired holds remain
76
+ visible until dismissed. The separate automatic background-task limits do
77
+ not change when an explicit hold is saved.
78
+
79
+ ## Costs and cancellation
80
+
81
+ Prefer a later check for external work that will continue while the box
82
+ sleeps. Use existing event follow-ups where available and automations for
83
+ recurring work. Very frequent checks can keep a box awake continuously when
84
+ each check and the idle-sleep timeout overlap the next check. A default-size
85
+ box awake for 24 hours uses 24 box-hours; larger sizes use more.
86
+
87
+ The commands act only on the authenticated current thread and require no
88
+ additional Agent permission. Both the agent and user can inspect saved
89
+ intent; users can cancel it in desktop or mobile without a running box.
90
+ Opening a thread on mobile can wake its box first. Desktop with automatic
91
+ waking off allows inspecting and cancelling while the box stays asleep.
92
+ Ordinary new messages and Stop leave saved checks and holds in place.
93
+ Cancel them separately when unattended work should end.
94
+
95
+ The desktop power menu shows the active hold deadline and next check for
96
+ the selected box. Its status lines open the responsible threads, where the
97
+ user can cancel each request. The Sleep action explains that holds will end
98
+ and a saved check can still wake the box later.
99
+
100
+ Manual sleep ends holds but leaves scheduled checks, which can wake the box
101
+ later. Reset or reboot ends holds because local processes may be lost.
102
+ Archiving or deleting the thread, or destroying its box, cancels pending
103
+ intent. Snapshot copies inherit neither checks nor holds.
104
+
105
+ A later prompt should identify the exact operation and inspect its status.
106
+ For a deployment, instruct the agent to inspect the existing deployment and
107
+ report, without launching another. Resuming later does not grant new
108
+ permission for side effects or bypass an outstanding approval.
@@ -0,0 +1,89 @@
1
+ # Vercel
2
+
3
+ Use this doc when a user asks how to connect Vercel, how the Vercel CLI signs
4
+ in on a box, why `vercel` says it isn't logged in, how SAML single sign-on works
5
+ for a Vercel team, or what `vercel logout` does on a box.
6
+
7
+ Each user connects Vercel once in the desktop app. boxes.dev keeps that Vercel
8
+ sign-in current and gives the Vercel CLI on all of the user's Template boxes and
9
+ devboxes the same login, so nobody needs to run `vercel login` on each box.
10
+
11
+ ## Connect Vercel
12
+
13
+ Open **Integrations → Vercel** in the desktop app and choose **Connect
14
+ Vercel**. The page shows a one-time code. Choose **Open Vercel**, check that the
15
+ code on Vercel matches, and choose **Allow Access**. When the account belongs
16
+ to a team that requires SAML, Vercel lists that team on the approval page, and
17
+ **Allow Access** stays disabled until the team is selected. The page updates on
18
+ its own after approval.
19
+
20
+ Vercel describes the request as coming from the Vercel CLI on a device named
21
+ boxes.dev. The location Vercel shows is a boxes.dev data center, not the user's
22
+ own location. Connecting needs the desktop app; the mobile app has no Vercel
23
+ page.
24
+
25
+ ## How The CLI Gets Its Login
26
+
27
+ boxes.dev writes the login to the file the Vercel CLI already reads,
28
+ `~/.local/share/com.vercel.cli/auth.json`, on each of the user's Template boxes
29
+ and devboxes. Every copy of the CLI uses it: a global install, `npx vercel`, or
30
+ a version installed in the project. Tools that read the same file, such as
31
+ `@vercel/oidc` refreshing `VERCEL_OIDC_TOKEN` in local development, use it
32
+ too. boxes.dev doesn't install the Vercel CLI.
33
+
34
+ The file holds a short-lived access token that boxes.dev replaces before it
35
+ expires; the renewable part of the sign-in stays encrypted in boxes.dev and is
36
+ never written to a box. Open terminals and running agents pick up a replacement
37
+ on their next `vercel` command. A command that was already running when the
38
+ token was replaced, such as `vercel dev`, can lose access to the Vercel API and
39
+ needs restarting.
40
+
41
+ Run `vercel whoami` on a box to check which Vercel account the CLI uses. If it
42
+ reports no login, the user hasn't connected Vercel yet; point them to
43
+ **Integrations → Vercel** in the desktop app.
44
+
45
+ `VERCEL_TOKEN` and `--token` take priority over the file, so a project or
46
+ command that sets them uses that token instead.
47
+
48
+ ## Signing In Or Out On A Box
49
+
50
+ Running `vercel login` on a box after connecting Vercel replaces the shared
51
+ login on every box, as long as it signs in to the same Vercel account. The
52
+ same happens when the CLI starts its own sign-in, for example for a team's
53
+ SAML single sign-on. A login for a different Vercel account stays on that one
54
+ box and is not shared.
55
+
56
+ `vercel logout` on any box ends the shared Vercel sign-in, which signs out the
57
+ Vercel CLI on every box, and the Vercel page then shows **Reconnect**. To stop
58
+ using the integration, choose **Disconnect Vercel** from the page's options
59
+ menu instead; that removes the login from every box.
60
+
61
+ Agents shouldn't run `vercel login` or `vercel logout` unless the user asks.
62
+
63
+ ## SAML Teams
64
+
65
+ A Vercel team that requires SAML single sign-on accepts the login only while
66
+ the team's SAML session lasts: 24 hours by default, or up to 30 days if the
67
+ team's identity provider sets a longer session. After that, `vercel` commands
68
+ for the team fail and the CLI asks for a new sign-in.
69
+
70
+ When the account belongs to teams that require SAML, the connected Vercel page
71
+ lists them under **Teams that require SAML**, each with a **Sign in** action.
72
+ Choosing **Sign in**, finishing the team's single sign-on on Vercel, selecting
73
+ the team, and allowing access renews the login on every box at once.
74
+
75
+ When a `vercel` command stops at a SAML sign-in prompt, give the user the
76
+ prompt's URL while the command is still waiting. If the command has already
77
+ ended, point the user to **Sign in** for that team on **Integrations →
78
+ Vercel**.
79
+
80
+ ## Reconnect Or Disconnect
81
+
82
+ The page shows **Vercel needs you to sign in again** when the shared sign-in
83
+ ends, either because someone ran `vercel logout` on a box or because Vercel
84
+ expired or revoked it. Until the user chooses **Reconnect**, `vercel` reports
85
+ that the token isn't valid.
86
+
87
+ **Disconnect Vercel** deletes the sign-in from boxes.dev, ends it on Vercel,
88
+ and removes the login file boxes.dev wrote on each box. A login the user
89
+ created with `vercel login` for a different account is left alone.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@boxes-dev/dvb-runtime",
3
- "version": "1.0.1079",
3
+ "version": "1.0.1081",
4
4
  "description": "Runtime for the boxes.dev CLI. Install @boxes-dev/dvb to use the CLI.",
5
5
  "homepage": "https://boxes.dev",
6
6
  "type": "module",
@@ -77,5 +77,5 @@
77
77
  "e2b": "^2.18.0",
78
78
  "ink-testing-library": "^4.0.0"
79
79
  },
80
- "devboxReleasedAt": "2026-10-15T22:32:18Z"
80
+ "devboxReleasedAt": "2026-10-16T19:12:34Z"
81
81
  }