@boxes-dev/dvb-runtime 1.0.1079 → 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.
@@ -0,0 +1,142 @@
1
+ # Google Cloud
2
+
3
+ Use this doc when a user asks how to connect Google Cloud, which Google Cloud
4
+ project a boxes.dev project uses, how `gcloud` and Google Cloud client
5
+ libraries get credentials on a box, how the Google sign-in stays current, or
6
+ why a tool or container is not using the managed Google identity.
7
+
8
+ The Google Cloud integration is currently available only to boxes.dev's
9
+ internal pilot accounts. If Google Cloud does not appear under
10
+ **Integrations**, the account has not been enabled for the pilot.
11
+
12
+ Each user signs in with their own Google account once, then chooses a Google
13
+ Cloud project for each boxes.dev project. Tools on the project's boxes act as
14
+ that Google account, with the permissions Google Cloud IAM already grants it.
15
+
16
+ ## Connect Google Cloud
17
+
18
+ Open **Integrations → Google Cloud** in the desktop app, or **Project
19
+ settings → Google Cloud** in the mobile app, and choose **Connect Google
20
+ Cloud**. The app opens Google's sign-in and consent page in the browser. Sign
21
+ in, keep the Google Cloud permission selected on the consent screen, and return
22
+ to boxes.dev; the app updates automatically. If the Google Cloud permission is
23
+ cleared on the consent screen, boxes.dev does not save the sign-in and asks the
24
+ user to connect again.
25
+
26
+ The web app shows the connection's status, but signing in to Google Cloud needs
27
+ the desktop or mobile app.
28
+
29
+ After sign-in, choose one of the Google Cloud projects the account can access,
30
+ then choose **Use this project**. boxes.dev does not pick a project
31
+ automatically. That choice applies to the current boxes.dev project only.
32
+ Another boxes.dev project can reuse the same Google sign-in and choose a
33
+ different Google Cloud project without signing in again.
34
+
35
+ The project list shows active projects the Google account can see, up to 500.
36
+ If the list is empty or is missing a project, someone who administers that
37
+ Google Cloud project needs to grant the account access. Choose **Refresh**
38
+ afterward; reconnecting is not required.
39
+
40
+ Google Cloud setup does not change the repository and does not require a
41
+ Template box snapshot. New terminals pick up Google Cloud automatically.
42
+ Existing Codex and Claude threads keep current work running, then pick up the
43
+ change before their next turn after that work finishes. Already-running shells
44
+ keep the environment they started with, so open a new terminal after
45
+ connecting, changing, or removing Google Cloud.
46
+
47
+ ## How Tools Receive Credentials
48
+
49
+ For a connected project, boxes.dev serves Google Cloud credentials on the
50
+ project's real boxes: the Template box and devboxes in an ordinary project, and
51
+ the assigned devboxes in a Team Template member project. It does this the same
52
+ way a Google Cloud virtual machine does, so `gcloud`, the Google Cloud client
53
+ libraries for Python, Node.js, Go and other languages, and tools built on
54
+ them find the credentials without configuration.
55
+
56
+ When one of those tools needs credentials, the local boxes.dev service asks
57
+ boxes.dev for a short-lived Google access token for the signed-in account. The
58
+ tool receives the token in memory; boxes.dev does not write a credentials file
59
+ to the box. The selected Google Cloud project becomes the default project, and
60
+ Google counts API quota against it.
61
+
62
+ A quick check in a new terminal is:
63
+
64
+ ```bash
65
+ gcloud auth list
66
+ gcloud config list
67
+ ```
68
+
69
+ The first command shows the Google account, and the second shows the selected
70
+ project.
71
+
72
+ If the Google sign-in has ended, `gcloud` and client libraries report that the
73
+ Google Cloud sign-in needs to be renewed and include a boxes.dev link that
74
+ opens the desktop app's Google Cloud page. `gcloud` keeps its own copy of a
75
+ recent token, so this message may appear up to an hour after the sign-in ends.
76
+ The desktop app also shows a **Google Cloud sign-in expired.** banner with a
77
+ **Reconnect Google Cloud** action that opens the Google Cloud page. The mobile
78
+ app shows the same warning with a **Reconnect** action that opens Google's
79
+ sign-in in the phone's browser. The banner's X hides the warning without
80
+ changing the connection.
81
+
82
+ The managed identity is the lowest-priority default. A `gcloud auth login`
83
+ account, application default credentials from `gcloud auth
84
+ application-default login`, a `GOOGLE_APPLICATION_CREDENTIALS` key file, or
85
+ credentials chosen directly in application code keep their normal Google
86
+ precedence and win over the boxes.dev identity.
87
+
88
+ ## Central Sign-In And Refresh
89
+
90
+ The renewable Google sign-in stays encrypted in boxes.dev and is never copied
91
+ to a Template box or devbox. boxes.dev issues each box short-lived access
92
+ tokens from that one sign-in, so every box uses the same current Google account
93
+ without a refresh token in a snapshot.
94
+
95
+ The local boxes.dev service may keep a still-valid token in memory until
96
+ shortly before it expires. That copy clears when the project changes its
97
+ Google Cloud project, disconnects, or the service restarts.
98
+
99
+ Google can still end the sign-in. Common reasons are removing boxes.dev's
100
+ access in the Google account's settings, a Google Workspace admin restricting
101
+ the app, or a Workspace policy that requires Google Cloud users to sign in
102
+ again after a set time. When that happens, choose **Reconnect** on the Google
103
+ Cloud page.
104
+
105
+ ## Change, Remove, Or Reconnect
106
+
107
+ The options menu on the desktop project row, and the **Options** section on
108
+ mobile, have these actions:
109
+
110
+ - **Change project** chooses a different Google Cloud project for this
111
+ boxes.dev project.
112
+ - **Reconnect Google Cloud** runs the Google sign-in again. The project choices
113
+ stay in place when the same Google account signs in. Signing in with a
114
+ different Google account removes the project choices made with the previous
115
+ account, so each project needs a new choice.
116
+ - **Remove from this project** stops future Google Cloud credentials for this
117
+ boxes.dev project. Other connected projects keep working.
118
+ - **Sign out of Google Cloud everywhere** deletes the Google sign-in from
119
+ boxes.dev, disconnects every boxes.dev project using it, and asks Google to
120
+ remove boxes.dev's access from the Google account.
121
+
122
+ When the sign-in needs attention, the page shows **Reconnect** and a **Sign out
123
+ of Google Cloud** link in place of the menu.
124
+
125
+ Existing shells and user-managed processes keep their prior environment after
126
+ any of these changes. A tool can keep using a token it already received until
127
+ that token expires, usually within an hour.
128
+
129
+ ## Containers And Current Limits
130
+
131
+ The Google Cloud integration applies to host-native terminals, Codex, Claude,
132
+ `gcloud`, and Google Cloud client libraries that use their standard credential
133
+ lookup. It does not publish credentials into Docker or other nested
134
+ containers. Configure container access to Google Cloud explicitly for now, and
135
+ do not copy the boxes.dev Google sign-in out as a workaround.
136
+
137
+ The integration provides access tokens only. Commands that need an identity
138
+ token for a specific audience, such as `gcloud auth print-identity-token` for a
139
+ private Cloud Run service, need a user-owned `gcloud auth login` account.
140
+
141
+ Each user has one Google sign-in, and each boxes.dev project uses one Google
142
+ Cloud project for that user.
@@ -76,7 +76,8 @@ Use this terminology consistently:
76
76
  ports, terminal sessions, runtime status, wake/sleep, reset, and resource
77
77
  indicators.
78
78
  - `mobile.md`: mobile monitoring and control, push notifications, responding to
79
- threads, file viewing, terminal access, and mobile/desktop differences.
79
+ threads, file viewing, terminal access, the shared Browser, and
80
+ mobile/desktop differences.
80
81
  - `cli.md`: common `dvb` workflows and how CLI use relates to desktop and
81
82
  mobile.
82
83
  - `agent-tools.md`: local coding-agent workflows for workstation `dvb`,
@@ -85,10 +86,13 @@ Use this terminology consistently:
85
86
  - `onbox-agent-tools.md`: the separate, narrow `dvb-onbox` surface available
86
87
  only to coding agents inside a Template box or devbox, including setup,
87
88
  snapshots, user-authorized delegated thread starts, project devbox
88
- folders, managing the project's automations, and pull request follow-ups.
89
+ folders, managing the project's automations, pull request follow-ups, and
90
+ publishing inline visuals, images, and videos.
89
91
  - `automations.md`: Thread Automations, scheduled/API-triggered runs, Slack and
90
92
  Linear-triggered runs, run history, capacity, spawned devbox threads, and
91
93
  automations created by agents.
94
+ - `unattended-work.md`: one-shot checks in the current thread, bounded
95
+ keep-awake requests, costs, cancellation and missed-check notices.
92
96
  - `slack.md`: Slack connection, identity linking, Slack-triggered automations,
93
97
  mentions, follow-ups, final replies, attachment import basics, and limits.
94
98
  - `linear.md`: Linear Agent App install, identity linking, assignment-triggered
@@ -99,6 +103,12 @@ Use this terminology consistently:
99
103
  - `aws.md`: central AWS IAM Identity Center sign-in, per-project account and
100
104
  role selection, the managed `boxes-dev` profile, credential precedence,
101
105
  refresh behavior, removal, and container limits.
106
+ - `google-cloud.md`: central Google sign-in, per-project Google Cloud project
107
+ selection, how `gcloud` and client libraries receive credentials, credential
108
+ precedence, reconnecting, removal, and container limits.
109
+ - `vercel.md`: connecting Vercel once for the Vercel CLI on every box, the
110
+ managed login file, `vercel login` and `vercel logout` on a box, SAML team
111
+ sign-in, reconnecting, and disconnecting.
102
112
  - `tailscale.md`: team-managed tailnet setup, Tailscale-policy-based project
103
113
  eligibility, tagged ephemeral project machines, stock CLI behavior, ordinary
104
114
  snapshot identity rotation, native cleanup, incident removal, and version-one
@@ -1,8 +1,8 @@
1
1
  # Mobile App
2
2
 
3
3
  The boxes.dev mobile app is for checking on work, replying to agents, opening a
4
- lightweight terminal, and inspecting files while you are away from the desktop
5
- workbench. It is not a full replacement for desktop setup, Git review, port
4
+ lightweight terminal, using the shared Browser, and inspecting files while you
5
+ are away from the desktop workbench. It is not a full replacement for desktop setup, Git review, port
6
6
  management, or the complete file tree.
7
7
 
8
8
  ## Install
@@ -81,11 +81,11 @@ Open a project to see its threads. The list can include:
81
81
  Opening the project, browsing its thread history, or editing an unstarted draft
82
82
  does not wake or connect to a machine. Mobile connects only after you open a
83
83
  live thread that has a runtime, or choose an action such as Send, Terminal,
84
- Files, snapshot, sleep, or destroy that needs one. A live devbox thread connects
85
- to that exact devbox rather than another project machine.
84
+ Browser, Files, snapshot, sleep, or destroy that needs one. A live devbox
85
+ thread connects to that exact devbox rather than another project machine.
86
86
 
87
87
  Tap the new-thread button to open a new-devbox draft directly. Long-press it
88
- to open the menu with **New devbox + thread** and, in an ordinary project,
88
+ to open the menu with **New thread** and, in an ordinary project,
89
89
  **New thread on Template box**. A Team Template member project has no template
90
90
  choice. If the project does not support devboxes, tapping opens a Template-box
91
91
  draft instead. The draft uses the project's last Codex or Claude choice from
@@ -147,6 +147,8 @@ text size as the composer. The composer can also show:
147
147
  - Claude Code model, reasoning, and permission mode choices in that same
148
148
  control when available;
149
149
  - context and rate-limit indicators;
150
+ - skill suggestions while you type a Codex `$` or Claude `/` token, including
151
+ in a new thread (see `threads-and-agents.md`);
150
152
  - follow-up mode and Codex queue controls;
151
153
  - pending Codex approvals that need your response;
152
154
  - image and file attachments when available;
@@ -157,7 +159,7 @@ speak a message to Codex or Claude. On first use, tap **Start dictation** and
157
159
  allow microphone access. Audio is sent to OpenAI to turn it into text. While
158
160
  dictation listens, the microphone turns solid blue and the composer has a blue
159
161
  outline. Words appear live at the end of your editable draft and stay
160
- highlighted while you speak, with a blue caret and a small microphone above it
162
+ highlighted while you speak, with a blue caret and a microphone below it
161
163
  marking where the next words will land. Tap the microphone again to stop
162
164
  listening; it turns off right away, and any last words appear a moment later.
163
165
  Then review, edit, and Send. Tapping Send while dictating adds the last words,
@@ -190,8 +192,14 @@ newer reading.
190
192
 
191
193
  When Codex waits for MCP servers during startup, the startup row names the
192
194
  servers that are still loading. If an MCP needs authentication again, mobile
193
- shows a dismissible notice that names it and directs you to **Integrations →
194
- MCPs** in the desktop app.
195
+ shows a dismissible notice that names it. For an MCP that boxes.dev manages,
196
+ the notice offers **Open MCPs**, which opens the project's MCPs screen where
197
+ you can sign in again. For an MCP installed directly on the Template box, the
198
+ notice directs you to **Template-managed MCPs** in the desktop app.
199
+
200
+ In a Team Template project, a warning above the thread names devbox setup that
201
+ failed, such as MCPs, Git identity, or AWS access. When MCPs need attention,
202
+ the warning offers **Open MCPs**.
195
203
 
196
204
  After you tap **Send** on an existing managed Codex or Claude thread, you can
197
205
  leave the thread immediately. boxes.dev keeps the follow-up in its delivery
@@ -236,13 +244,21 @@ is told that the command stopped, so you can ask it to run the command again.
236
244
 
237
245
  Claude Code model and reasoning selections stay with the thread, sync with the
238
246
  desktop composer, and remain selected when the thread is reopened or resumed.
247
+ For supported Claude threads, the **Reasoning** section of the model options
248
+ also offers **Ultracode**. Claude will run large tasks in parallel at a much
249
+ higher usage rate. Effort stays separate, and the choice
250
+ belongs to this thread rather than becoming the default for the next one.
251
+ If Claude cannot use it, the menu explains that and the thread continues
252
+ normally. A running Workflow card has its own **Stop** action, which stops
253
+ only that workflow. See `threads-and-agents.md` for availability and settings.
254
+
239
255
  While an agent turn is active, the mobile composer shows **Stop** even after
240
256
  you type or attach files. Stopping preserves text and attachments that are
241
257
  still drafts in the composer so you can send them as soon as the turn finishes
242
258
  stopping.
243
259
 
244
- Use the terminal button in a session when you need a shell for the thread's
245
- current runtime.
260
+ Choose **… → Open Terminal** in a session when you need a shell for the
261
+ thread's current runtime.
246
262
 
247
263
  Choose **… → Agent permissions** in an open thread to view or change what
248
264
  agents on that thread's devbox or Template box can do. Each row shows the
@@ -305,6 +321,16 @@ older screenshot history when needed. Pinch or double-tap to zoom; while
305
321
  zoomed in, drag to pan. Inline screenshots and screenshot file links appear
306
322
  together in conversation order. Normal web links will open in your browser.
307
323
 
324
+ Images and videos that an agent presents in its final reply appear as a row of
325
+ up to four previews with captions; when there are more than four files, the
326
+ fourth slot shows how many more there are. Tap a preview to open the viewer,
327
+ which shows one file at a time. The arrow buttons move between files, and you
328
+ can also swipe between images at their normal size. Videos use the standard
329
+ player controls and won't play until you start them; moving to another file or
330
+ closing the viewer stops playback. The download button opens the file in your
331
+ browser. While thread search highlights a match in that reply, its files appear
332
+ as ordinary links.
333
+
308
334
  Mobile can open file and diff links from thread activity. The file viewer
309
335
  supports text files with syntax highlighting, image and PDF previews, downloads,
310
336
  retry after errors, highlighted lines, and diff mode with added and removed line
@@ -338,6 +364,42 @@ longer available, go back to the thread and reopen the terminal.
338
364
  The terminal includes mobile accessory controls for Ctrl, paste, special keys,
339
365
  and keyboard visibility.
340
366
 
367
+ ## Browser
368
+
369
+ Choose **… → Open Browser** in a thread's header to open Browser on that
370
+ thread's devbox or Template box, waking it if it's asleep. It is the same
371
+ Chromium session as the desktop Browser pane, with the same tabs, signed-in
372
+ sites, and profile, and agents on the box use it too. If the box's browser
373
+ isn't running yet, opening Browser starts it.
374
+
375
+ Opening Browser on a phone resizes that shared browser to the phone's page
376
+ area, so sites use their narrow-screen layout. It is a size change only: sites
377
+ still see a desktop browser, with desktop scrollbars and no touch events. The
378
+ desktop pane and agent screenshots also get the phone size while it lasts.
379
+ With the default streaming setting, the desktop pane keeps showing its last
380
+ picture. Moving the pointer into the desktop pane, or focusing it, resizes the
381
+ browser back to the pane. On the phone, the first touch after that resizes it
382
+ to the phone again and does nothing else.
383
+
384
+ Tap to click and drag with one finger to scroll. Tapping a text field opens
385
+ the keyboard; tapping elsewhere on the page closes it. While the keyboard is
386
+ open, the page keeps its size and shifts up to keep the tapped field in view.
387
+ The keyboard button in the bottom toolbar opens or closes the keyboard for
388
+ fields that don't open it themselves. The address field opens a URL or domain
389
+ in the current tab. The toolbar also has back, forward, reload, and a tab
390
+ count that opens **Tabs**, where you can switch tabs, open a **New tab**, or
391
+ **Close tab**.
392
+
393
+ Page dialogs (alerts, confirmations, prompts, and "leave this page?" checks)
394
+ and site permission requests appear as sheets with the page's choices. A
395
+ prompt dialog accepts its default text. If the browser stops, **Restart
396
+ Browser** starts it again with the same profile and reopens its tabs.
397
+
398
+ While Browser is open with the app in the foreground, the box stays awake, as
399
+ it does for an open thread. Browser disconnects while the app is in the
400
+ background and reconnects when you return. Element review comments, downloads, file uploads, and passkey sign-in
401
+ are desktop Browser workflows.
402
+
341
403
  ## Notifications
342
404
 
343
405
  Push notifications can open the relevant project thread from a cold start or
@@ -352,14 +414,34 @@ the thread. The app icon badge counts unread threads across the signed-in
352
414
  accounts. An account starts receiving notifications on a phone after it has
353
415
  been opened there once.
354
416
 
355
- Use mobile settings to turn the unread badge on or off.
417
+ In **Settings → Notifications**, **Quiet hours** sets one daily interval shared
418
+ with desktop and the account's other phones. Each device uses its own timezone.
419
+ The phone reports its zone when it connects; after travel, open the app to update
420
+ it. While closed, it uses the last reported zone. Quiet hours need the updated
421
+ mobile app to have opened on that phone; older apps that have never reported a
422
+ zone retain their previous delivery behavior.
423
+
424
+ Under **Pause notifications**, **Pause** pauses agent alerts for one hour on
425
+ every device for this account until the same end time. **Resume** ends the pause early;
426
+ daily quiet hours still apply. Quiet hours and pause cover replies, failures,
427
+ input requests, and teammate-agent alerts, while unread counts and pending
428
+ requests remain available. Suppressed alerts are not replayed. Notifications
429
+ already being prepared or delivered can still arrive after a change.
430
+
431
+ **Push notifications** controls alerts for the current account on this phone.
432
+ It stays off across routine notification registration and does not affect other
433
+ devices or the independent **Unread app icon badge** setting.
434
+ If the phone's settings deny notification permission, the switch stays off.
435
+ Tap the row to open the phone's settings and allow notifications.
356
436
 
357
437
  ## Settings
358
438
 
359
- A project's gear button opens **Project settings**, which has two rows:
439
+ A project's gear button opens **Project settings**, which has these rows:
360
440
 
361
441
  - **Agent permissions**, for the shared permissions that the project's
362
442
  devboxes follow unless they were configured separately;
443
+ - **MCPs**, for the MCP servers Codex and Claude use in the project (see
444
+ [MCPs](#mcps));
363
445
  - **App settings**, which opens the app-wide settings below.
364
446
 
365
447
  The **Settings** tab on Home opens the app-wide settings directly. They
@@ -371,7 +453,8 @@ include:
371
453
  - billing usage summary;
372
454
  - an invite link and QR code you can share with someone who wants to try
373
455
  boxes.dev (the same link is on the Account page in the web app);
374
- - unread app icon badge preference;
456
+ - quiet hours, a one-hour notification pause, phone alerts, and unread app icon
457
+ badge preference;
375
458
  - theme, monospace font, and thread text size;
376
459
  - release package details and refresh controls in installed builds;
377
460
  - account deletion.
@@ -423,6 +506,45 @@ attention or a key needs replacing. Dismissing the banner hides it until the
423
506
  app restarts or another account starts failing; dismissing a sign-in reminder
424
507
  does not hide a later failure.
425
508
 
509
+ ### MCPs
510
+
511
+ Open a project, tap its gear button, then choose **MCPs** to manage the MCP
512
+ servers Codex and Claude use on that project's devboxes.
513
+ This is the same list as **Integrations → MCPs** in the desktop app, including
514
+ MCPs marked **All projects** and MCPs from a Team Template. Each MCP shows a
515
+ row for Codex and one for Claude with its state: **Connected**, **Sign-in
516
+ needed**, **Signing in**, or **Not added**.
517
+
518
+ Tap **Add MCP** and paste the server URL, or the Codex or Claude setup command
519
+ the provider gave you, then tap **Continue**. boxes.dev checks how the server
520
+ signs in, so the form usually asks only for the name, **Available in**, and
521
+ which agents to add it to. A server that also works without an account shows
522
+ **Sign in** and **Don't sign in**; a command with headers, or a server that
523
+ needs an API key, asks for the header values. **Advanced** holds the URL and
524
+ the name the agents use. Commands for MCPs that run on the box itself,
525
+ legacy SSE servers, and custom OAuth clients can't be added here; run them on
526
+ the Template box.
527
+
528
+ Tap an agent that isn't added to add it. For an MCP that uses sign-in, this
529
+ starts sign-in for that agent, so connecting both agents usually means
530
+ approving access twice. Tap an added agent to sign in again or to remove the
531
+ MCP from that agent. The **…** menu on an MCP saves its API key or headers,
532
+ offers **Use without signing in** while no agent is signed in to a server
533
+ that also works without an account, and removes the MCP from every devbox.
534
+ MCPs from a Team Template can't be removed or switched to no sign-in from the
535
+ app; you can still sign in to them and enter your own API key.
536
+
537
+ Sign-in opens the provider's page in a sign-in window inside the app. After
538
+ you approve access, the window will close and the agent will show
539
+ **Connected**; boxes.dev applies the sign-in to all of the project's
540
+ devboxes, including sleeping ones when they wake. If the app can't receive the
541
+ sign-in directly, it opens the page in your browser instead. After you
542
+ approve, the browser will show a page that can't load; copy that page's full
543
+ address, paste it into the app, and tap **Finish sign-in**.
544
+
545
+ The MCPs screen requires an updated mobile app; an older installed app needs an
546
+ app-store update.
547
+
426
548
  ## Mobile Versus Desktop
427
549
 
428
550
  Use desktop for setup, full project orientation, file upload/download workflows,
@@ -431,6 +553,7 @@ detailed review.
431
553
 
432
554
  Use mobile when you want to monitor progress, answer questions, send a quick
433
555
  follow-up, review or change agent permissions, reconnect a Codex or Claude
434
- account, take a Template-box snapshot,
435
- inspect a linked file or diff, open a shell, sleep or destroy a devbox, or
436
- check billing/status away from the desktop.
556
+ account, add or sign in to an MCP, take a Template-box snapshot,
557
+ inspect a linked file or diff, open a shell, check a page in the shared
558
+ Browser, sleep or destroy a devbox, or check billing/status away from the
559
+ desktop.