@boxes-dev/dvb-runtime 1.0.1078 → 1.0.1080
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.
- package/dist/bin/dvb.mjs +1547 -218
- package/dist/bin/dvbd.mjs +6 -6
- package/dist/product-docs/references/agent-tools.md +6 -1
- package/dist/product-docs/references/automations.md +45 -1
- package/dist/product-docs/references/aws.md +5 -0
- package/dist/product-docs/references/cli.md +54 -0
- package/dist/product-docs/references/desktop-workbench.md +106 -32
- package/dist/product-docs/references/files-git-and-review.md +8 -1
- package/dist/product-docs/references/fork-workflows.md +2 -2
- package/dist/product-docs/references/google-cloud.md +142 -0
- package/dist/product-docs/references/index.md +12 -2
- package/dist/product-docs/references/managed-environment-files.md +14 -1
- package/dist/product-docs/references/member-managed-files.md +9 -0
- package/dist/product-docs/references/mobile.md +139 -16
- package/dist/product-docs/references/onbox-agent-tools.md +183 -32
- package/dist/product-docs/references/ports-terminal-and-runtime.md +112 -27
- package/dist/product-docs/references/project-setup.md +1 -1
- package/dist/product-docs/references/security-and-data.md +20 -0
- package/dist/product-docs/references/team-template.md +69 -7
- package/dist/product-docs/references/threads-and-agents.md +110 -35
- package/dist/product-docs/references/troubleshooting.md +48 -7
- package/dist/product-docs/references/unattended-work.md +108 -0
- package/dist/product-docs/references/vercel.md +89 -0
- package/package.json +2 -2
|
@@ -300,6 +300,43 @@ The template's editing machine does not receive these settings. See
|
|
|
300
300
|
`threads-and-agents.md` for how boxes.dev writes the settings on each box, how
|
|
301
301
|
lists combine, and which keys are reserved.
|
|
302
302
|
|
|
303
|
+
## Team Agent Permissions
|
|
304
|
+
|
|
305
|
+
The **Agent permissions** card on the Team Template page sets the project
|
|
306
|
+
agent permissions for projects that use the template: creating devboxes and
|
|
307
|
+
threads, destroying devboxes, messaging other agents and teammates' agents,
|
|
308
|
+
updating thread titles, folder access, and reading other threads. Only team
|
|
309
|
+
admins can edit it. Until an admin saves it, each project keeps its own
|
|
310
|
+
permissions.
|
|
311
|
+
|
|
312
|
+
For managed projects, the admin chooses one of two modes:
|
|
313
|
+
|
|
314
|
+
- **Editable defaults:** each Member project follows the template's values
|
|
315
|
+
until the member changes a permission in Project settings. A permission the
|
|
316
|
+
member changed stays as they set it when the template changes. **Use Team
|
|
317
|
+
Template permissions** in Project settings returns every permission to the
|
|
318
|
+
template's values.
|
|
319
|
+
- **Locked:** every Member project uses the template's values, and members
|
|
320
|
+
can't change them in Project settings. Locking replaces any permissions
|
|
321
|
+
members chose themselves. Unlocking keeps everyone on the template's values
|
|
322
|
+
until a member changes one.
|
|
323
|
+
|
|
324
|
+
The first time an admin saves editable defaults for a template that already
|
|
325
|
+
has Member projects, boxes.dev asks whether those projects should move to the
|
|
326
|
+
template's values or keep their current permissions as the members' own
|
|
327
|
+
choices. Either way, new Member projects will follow the template.
|
|
328
|
+
|
|
329
|
+
In both modes, members can still change permissions on an individual box from
|
|
330
|
+
its thread header, and agents can still request permission for their own box.
|
|
331
|
+
While the template is locked, a permission request can't be approved for the
|
|
332
|
+
whole project. Independent projects copy the template's values when they are
|
|
333
|
+
created; their owners can change them afterward, and the lock doesn't apply.
|
|
334
|
+
|
|
335
|
+
An agent with Team Template access can read and change these permissions with
|
|
336
|
+
`dvb-onbox team-template settings` (the `agent_permissions` section in
|
|
337
|
+
`onbox-agent-tools.md`). Only a team admin can grant that access, and the
|
|
338
|
+
first-save and lock choices above still apply.
|
|
339
|
+
|
|
303
340
|
## Settings For New Projects
|
|
304
341
|
|
|
305
342
|
The **Settings for new projects** card controls everything else a new project
|
|
@@ -360,6 +397,14 @@ to establish its shared saved environment. A failure preserves the prior saved
|
|
|
360
397
|
version, discards any machine that may have been partly changed, and never
|
|
361
398
|
modifies an admin's editing session.
|
|
362
399
|
|
|
400
|
+
boxes.dev prepares a few devboxes for each member project ahead of time. For a
|
|
401
|
+
minute or two after a maintenance run makes a new saved version current, while
|
|
402
|
+
those are replaced, a new devbox can start from one prepared from the previous
|
|
403
|
+
saved version if the startup and teardown scripts and the box size have not
|
|
404
|
+
changed. That devbox keeps the previous version's files and repositories. A
|
|
405
|
+
version an admin saves from an editing session applies to every new devbox as
|
|
406
|
+
soon as it becomes current.
|
|
407
|
+
|
|
363
408
|
A maintenance trigger waits behind an active editing session and starts after
|
|
364
409
|
the session closes. Multiple triggers coalesce into the pending run. If the
|
|
365
410
|
script succeeds but saving fails, the detail page offers **Retry save** and
|
|
@@ -440,13 +485,30 @@ another.
|
|
|
440
485
|
|
|
441
486
|
## Creating A Project
|
|
442
487
|
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
Select the exact template,
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
|
|
488
|
+
Start the ordinary new-project flow and choose **Start from a Team Template**.
|
|
489
|
+
The picker shows only templates with a current saved version and does not
|
|
490
|
+
preselect one. Select the exact template, name the project and complete
|
|
491
|
+
**Needed to create the project**, which brings required environment values
|
|
492
|
+
and all member files together. **Optional values** starts collapsed; these
|
|
493
|
+
can be added now or later in Project settings. Independent projects also
|
|
494
|
+
offer coding-agent choices; at least one must be selected when the template
|
|
495
|
+
includes setup instructions. Team defaults remain available for review.
|
|
496
|
+
|
|
497
|
+
The persistent bottom actions identify missing items and link to their
|
|
498
|
+
fields. **Create project** marks missing fields and focuses the first one.
|
|
499
|
+
Checks still enforce GitHub access, billing and the template's actual
|
|
500
|
+
requirements; values being present does not prove the credentials work.
|
|
501
|
+
|
|
502
|
+
**Change template** keeps the active draft in memory, and **Back to setup**
|
|
503
|
+
returns to it from the picker. Selecting a different template or closing setup
|
|
504
|
+
asks before discarding meaningful entries. Reloading clears unsaved entries; there is
|
|
505
|
+
no cross-session draft storage. Creation errors keep the entries for retry.
|
|
506
|
+
|
|
507
|
+
Git identity appears as an account summary. **Edit account identity** opens
|
|
508
|
+
the fields, and changes update the account identity when the project is
|
|
509
|
+
created. An opted-out account stays opted out unless the member chooses
|
|
510
|
+
**Turn on for your account**. This does not create a project-specific Git
|
|
511
|
+
identity.
|
|
450
512
|
|
|
451
513
|
For saved GitHub repositories, project creation checks the member's current
|
|
452
514
|
boxes.dev GitHub connection and pull/push access. Any GitHub maintenance watch,
|
|
@@ -22,7 +22,7 @@ than separate agent choices.
|
|
|
22
22
|
|
|
23
23
|
Start threads from the desktop thread list.
|
|
24
24
|
|
|
25
|
-
Use **New
|
|
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
|
|
259
|
-
|
|
260
|
-
|
|
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
|
-
|
|
580
|
-
|
|
581
|
-
|
|
582
|
-
|
|
583
|
-
|
|
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
|
|
665
|
-
to Codex on that machine. Each row shows
|
|
666
|
-
|
|
667
|
-
|
|
668
|
-
|
|
669
|
-
|
|
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
|
-
|
|
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.
|
|
756
|
-
|
|
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
|
|
876
|
-
|
|
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**
|
|
1046
|
-
|
|
1047
|
-
|
|
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
|
|
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
|
|
1066
|
-
with accept and dismiss controls, and selecting any
|
|
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
|
|
1096
|
-
owner's agents published in its replies, without starting the
|
|
1097
|
-
A
|
|
1098
|
-
currently read the thread where it was published. Copying the
|
|
1099
|
-
teammate's thread, another conversation, or Slack does not give
|
|
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
|
|
|
@@ -1210,6 +1275,16 @@ Thread rows can show unread and active indicators so users can see which
|
|
|
1210
1275
|
threads need attention. Desktop and mobile notifications can also point users
|
|
1211
1276
|
back to threads that finished, need input, or changed state.
|
|
1212
1277
|
|
|
1278
|
+
While boxes.dev is in the foreground, phone alerts stay quiet for all projects.
|
|
1279
|
+
When boxes.dev is in the background and the user is using the computer,
|
|
1280
|
+
phone alerts stay quiet for the selected project.
|
|
1281
|
+
This requires an updated desktop app and an enabled desktop notification,
|
|
1282
|
+
sound, or attention effect. Phone alerts resume after five minutes without
|
|
1283
|
+
keyboard or mouse input, or when the background desktop app detects a locked
|
|
1284
|
+
screen. Quitting the app or sleeping the computer releases the desktop claim
|
|
1285
|
+
within about 45 seconds. Other projects remain eligible for phone alerts. Unread markers and
|
|
1286
|
+
badges continue to sync across devices.
|
|
1287
|
+
|
|
1213
1288
|
**Mute notifications** turns off one thread's notifications for finished,
|
|
1214
1289
|
failed, and interrupted turns and keeps those turns from marking it unread. A
|
|
1215
1290
|
request for input still notifies and marks the thread. A muted thread shows a
|
|
@@ -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
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
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
|
|
387
|
-
installation
|
|
388
|
-
|
|
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.
|
|
3
|
+
"version": "1.0.1080",
|
|
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-
|
|
80
|
+
"devboxReleasedAt": "2026-10-16T15:46:35Z"
|
|
81
81
|
}
|