@boxes-dev/dvb-runtime 1.0.963 → 1.0.964
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 +160 -63
- package/dist/bin/dvbd.mjs +6 -6
- package/dist/product-docs/references/agent-tools.md +10 -4
- package/dist/product-docs/references/automations.md +14 -11
- package/dist/product-docs/references/aws.md +6 -5
- package/dist/product-docs/references/billing-and-limits.md +13 -5
- package/dist/product-docs/references/cli.md +22 -12
- package/dist/product-docs/references/core-concepts.md +34 -21
- package/dist/product-docs/references/desktop-workbench.md +27 -21
- package/dist/product-docs/references/files-git-and-review.md +46 -22
- package/dist/product-docs/references/fork-workflows.md +42 -15
- package/dist/product-docs/references/getting-started.md +49 -31
- package/dist/product-docs/references/glossary.md +10 -6
- package/dist/product-docs/references/index.md +17 -13
- package/dist/product-docs/references/mobile.md +26 -23
- package/dist/product-docs/references/onbox-agent-tools.md +14 -7
- package/dist/product-docs/references/ports-terminal-and-runtime.md +11 -9
- package/dist/product-docs/references/project-setup.md +29 -17
- package/dist/product-docs/references/security-and-data.md +38 -19
- package/dist/product-docs/references/tailscale.md +15 -11
- package/dist/product-docs/references/team-template.md +129 -82
- package/dist/product-docs/references/template-box-environment.md +10 -8
- package/dist/product-docs/references/threads-and-agents.md +90 -44
- package/dist/product-docs/references/troubleshooting.md +39 -16
- package/package.json +2 -2
|
@@ -37,13 +37,21 @@ does not resize existing boxes.
|
|
|
37
37
|
Awake Template boxes and awake devboxes consume box-hours. Sleeping runtimes do
|
|
38
38
|
not consume active box-hours while they are asleep. Idle devboxes can sleep
|
|
39
39
|
automatically, and users can also sleep devboxes manually. boxes.dev internal
|
|
40
|
-
maintenance wakes do not consume box-hours.
|
|
40
|
+
maintenance wakes on a user's existing devbox do not consume box-hours. The
|
|
41
|
+
separate Team Template source behavior is described below.
|
|
41
42
|
|
|
42
43
|
While a team admin has taken control of the Team Template, its awake editing
|
|
43
|
-
machine uses that admin's box-hours.
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
44
|
+
machine uses that admin's box-hours. The Team Template's clean shared source is
|
|
45
|
+
normally asleep. Its brief maintenance and boxes.dev update wakes are
|
|
46
|
+
attributed to a team admin for usage; they do not create a project or consume a
|
|
47
|
+
member's devbox slot. A project created from the active Team Template release
|
|
48
|
+
uses a normal project slot and the creating member's normal runtime
|
|
49
|
+
entitlement.
|
|
50
|
+
|
|
51
|
+
A Team Template member project has no personal Template box to bill. Its idle
|
|
52
|
+
prepared devboxes stay sleeping and do not use box-hours or awake-devbox
|
|
53
|
+
capacity. After a prepared devbox is assigned and wakes for the member, it is
|
|
54
|
+
accounted for exactly like that member's other devboxes.
|
|
47
55
|
|
|
48
56
|
The desktop titlebar can show a usage icon next to the project selector; hover
|
|
49
57
|
it for current box-hour usage and awake devbox usage. The billing page shows
|
|
@@ -184,7 +184,9 @@ dvb agents [project] [--json | --bell]
|
|
|
184
184
|
```
|
|
185
185
|
|
|
186
186
|
This opens a live terminal switchboard for existing agent threads on the
|
|
187
|
-
project's
|
|
187
|
+
project's devboxes and, when it has one, its Template box. A Team Template
|
|
188
|
+
member project has only its Devboxes section and shows any recoverable setup
|
|
189
|
+
warning without inventing a Template target. If the project is omitted and more than one
|
|
188
190
|
is available, choose one from the prompt. If there are no projects yet, the CLI
|
|
189
191
|
points you to the coding-agent-led `dvb agent-init` flow or desktop setup.
|
|
190
192
|
The selector can be a project alias or exact fingerprint.
|
|
@@ -230,17 +232,19 @@ unavailable, and stale content do not clear it.
|
|
|
230
232
|
|
|
231
233
|
Use `p` to pin or unpin an eligible Template-box thread or devbox anchor, `r`
|
|
232
234
|
to rename a thread, and `x` to archive or restore it. On an archived
|
|
233
|
-
cold-storage thread, `x`
|
|
234
|
-
|
|
235
|
+
cold-storage thread, `x` opens the available restore choice. Ordinary projects
|
|
236
|
+
can use the current Template box or a new devbox; Team Template member projects
|
|
237
|
+
restore only to a new devbox. Empty rename input
|
|
235
238
|
returns the automatic title. Codex archive updates the saved native session
|
|
236
239
|
before the shared list; Claude archive changes the shared list without waking
|
|
237
240
|
its machine. If an action is not safe for the selected row, the switchboard
|
|
238
241
|
explains why.
|
|
239
242
|
|
|
240
243
|
Press `n` to start a thread on the selected item's machine. Select a thread on
|
|
241
|
-
the Template box or a devbox group/thread.
|
|
242
|
-
targets the Template box.
|
|
243
|
-
|
|
244
|
+
the Template box or a devbox group/thread. In an ordinary empty project, `n`
|
|
245
|
+
targets the Template box. A Team Template member project has no Template
|
|
246
|
+
target. Press `N` to start a thread on a new devbox created from the project's
|
|
247
|
+
current reusable source. The compact composer shows its target in the
|
|
244
248
|
border and the current agent settings on one status line. Press `Tab` (or
|
|
245
249
|
`Shift+Tab`) to move focus across those settings like form fields: arrow keys
|
|
246
250
|
change the focused value, typing jumps to a matching option by name, and `Esc`
|
|
@@ -254,7 +258,7 @@ terminal interface as soon as it is ready. The Codex or Claude choice is shared
|
|
|
254
258
|
for the project with desktop and mobile, so a change from any surface becomes
|
|
255
259
|
the default for the next new draft on every surface. Model, reasoning, and
|
|
256
260
|
speed defaults are shared per Template box or devbox. A new-devbox draft uses
|
|
257
|
-
|
|
261
|
+
the project's source defaults until the devbox exists. Claude CLI remains a
|
|
258
262
|
surface-specific Claude mode. Press `Esc` before submission to discard a blank
|
|
259
263
|
draft or keep a non-blank draft; while waiting for `Ctrl+O`, `Esc` cancels only
|
|
260
264
|
the automatic open and leaves the agent running.
|
|
@@ -323,10 +327,12 @@ message there. If the project is omitted, the CLI auto-selects the only project
|
|
|
323
327
|
or shows the same project picker as `dvb agents`.
|
|
324
328
|
|
|
325
329
|
When starting a new thread without `--devbox`, the command creates a devbox from
|
|
326
|
-
the
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
+
the project's current reusable source. For an ordinary project, that is the
|
|
331
|
+
latest completed Template-box snapshot; if none exists, the command asks you to
|
|
332
|
+
take one without creating a thread or devbox. For a Team Template member
|
|
333
|
+
project, it uses the current saved version and any prepared devbox. With
|
|
334
|
+
`--devbox`, it uses that existing devbox in the selected project; a reusable
|
|
335
|
+
source is not required and deleting the new thread never deletes that devbox.
|
|
330
336
|
|
|
331
337
|
With `--resume`, the command opens the exact existing boxes.dev-managed thread
|
|
332
338
|
whose native Codex thread ID or Claude session ID matches in the selected
|
|
@@ -499,7 +505,7 @@ for adding the pinning step to an application.
|
|
|
499
505
|
|
|
500
506
|
## Snapshots, Devbox Creation, Sleep, Wake, And Reset
|
|
501
507
|
|
|
502
|
-
|
|
508
|
+
For an ordinary project's Template box, use:
|
|
503
509
|
|
|
504
510
|
```bash
|
|
505
511
|
dvb checkpoint <devbox>
|
|
@@ -507,6 +513,10 @@ dvb checkpoint <devbox>
|
|
|
507
513
|
|
|
508
514
|
to capture a new snapshot of the Template box.
|
|
509
515
|
|
|
516
|
+
Team Template member projects have no personal Template box, so checkpoint and
|
|
517
|
+
other Template-only commands are not available for them. Their team admins save
|
|
518
|
+
new versions through the Team Template editor.
|
|
519
|
+
|
|
510
520
|
A local coding agent can create an environment-only devbox without creating a
|
|
511
521
|
thread:
|
|
512
522
|
|
|
@@ -5,9 +5,11 @@ structured.
|
|
|
5
5
|
|
|
6
6
|
## Project
|
|
7
7
|
|
|
8
|
-
A project is one codebase in boxes.dev.
|
|
9
|
-
for that project. A Template
|
|
10
|
-
|
|
8
|
+
A project is one codebase in boxes.dev. Most project setup paths create one
|
|
9
|
+
Template box for that project. A Team Template can instead let members create
|
|
10
|
+
projects without personal Template boxes; those projects still own their
|
|
11
|
+
devboxes, threads, settings, and integrations. Set up another project when a
|
|
12
|
+
different codebase needs its own environment.
|
|
11
13
|
|
|
12
14
|
## Team Template
|
|
13
15
|
|
|
@@ -15,14 +17,17 @@ A Team Template is one named, team-wide, versioned starting environment for new
|
|
|
15
17
|
projects. It is not a project's Template box. A team can have several Team
|
|
16
18
|
Templates for different project shapes. Each has its own release history and
|
|
17
19
|
editing lock. Team admins publish releases, and current team members can create
|
|
18
|
-
independent projects from a selected template's active
|
|
19
|
-
supplying a local repository.
|
|
20
|
-
|
|
20
|
+
independent projects from a selected template's active saved version without
|
|
21
|
+
supplying a local repository. A Team Template can create an ordinary project
|
|
22
|
+
with its own Template box or a member project whose future devboxes keep using
|
|
23
|
+
the Team Template's current saved files. See `team-template.md` for the editing,
|
|
24
|
+
saved-version, setup, Git access, and copied-data workflow.
|
|
21
25
|
|
|
22
26
|
## Template box
|
|
23
27
|
|
|
24
|
-
The Template box is the persistent base machine for
|
|
25
|
-
|
|
28
|
+
The Template box is the persistent base machine for an ordinary project. It is
|
|
29
|
+
the source that future devboxes start from. Team Template member projects do
|
|
30
|
+
not have one.
|
|
26
31
|
|
|
27
32
|
Use the Template box for:
|
|
28
33
|
|
|
@@ -36,9 +41,10 @@ is intentionally part of the shared baseline.
|
|
|
36
41
|
|
|
37
42
|
## Devbox
|
|
38
43
|
|
|
39
|
-
A devbox is an isolated machine created from
|
|
40
|
-
|
|
41
|
-
|
|
44
|
+
A devbox is an isolated machine created from the project's reusable source: an
|
|
45
|
+
ordinary project's Template-box snapshot or a member project's current Team
|
|
46
|
+
Template saved version. Each devbox has its own filesystem, services, memory,
|
|
47
|
+
local app state, terminal sessions, ports, and agent threads.
|
|
42
48
|
|
|
43
49
|
Use devboxes for normal task work: features, bug fixes, refactors, experiments,
|
|
44
50
|
review tasks, and integration-triggered automations. Devboxes are meant to be
|
|
@@ -48,7 +54,8 @@ project uses, then sleep or destroy devboxes you no longer need.
|
|
|
48
54
|
## Thread
|
|
49
55
|
|
|
50
56
|
A thread is a conversation with a coding agent connected to a runtime. In
|
|
51
|
-
boxes.dev, threads
|
|
57
|
+
boxes.dev, threads run on a devbox or, in an ordinary project, on the Template
|
|
58
|
+
box.
|
|
52
59
|
|
|
53
60
|
The agent is Codex or Claude, depending on what is enabled and authenticated.
|
|
54
61
|
In the desktop app, GUI and Terminal are two views of that same conversation,
|
|
@@ -58,7 +65,8 @@ spawned by an automation or integration.
|
|
|
58
65
|
## Runtime
|
|
59
66
|
|
|
60
67
|
A runtime is the actual machine a pane or thread is connected to. The selected
|
|
61
|
-
runtime is whichever Template box
|
|
68
|
+
runtime is whichever devbox or available Template box is currently selected in
|
|
69
|
+
the app.
|
|
62
70
|
|
|
63
71
|
The selected runtime matters because terminals, forwarded ports, file views, git
|
|
64
72
|
status, wake/sleep controls, and runtime usage indicators follow it. If a user
|
|
@@ -67,10 +75,12 @@ Template box, they operate on the Template box.
|
|
|
67
75
|
|
|
68
76
|
## Snapshot
|
|
69
77
|
|
|
70
|
-
A snapshot is a saved state of
|
|
71
|
-
from. A snapshot includes the useful machine state needed to
|
|
72
|
-
come up like the Template box did at snapshot time, including
|
|
73
|
-
and running development state when supported.
|
|
78
|
+
A snapshot is a saved state of an ordinary project's Template box that future
|
|
79
|
+
devboxes can start from. A snapshot includes the useful machine state needed to
|
|
80
|
+
make a new devbox come up like the Template box did at snapshot time, including
|
|
81
|
+
filesystem state and running development state when supported. Team Template
|
|
82
|
+
member projects use the Team Template's current saved version instead; team
|
|
83
|
+
admins update it from the Team Template editor.
|
|
74
84
|
|
|
75
85
|
Take a new snapshot after updating the Template box in a way future devboxes
|
|
76
86
|
should inherit, such as installing dependencies, changing setup, restoring a
|
|
@@ -120,10 +130,13 @@ it can be woken when the awake devbox limit is reached.
|
|
|
120
130
|
|
|
121
131
|
## Template box Snapshots Versus Devbox Work
|
|
122
132
|
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
133
|
+
For an ordinary project, the Template box is the source of future devbox state.
|
|
134
|
+
For a Team Template member project, the shared Team Template saved version is
|
|
135
|
+
the source. A devbox is where a specific task should happen. If useful setup
|
|
136
|
+
was discovered while working on an ordinary-project devbox, apply that setup to
|
|
137
|
+
the Template box and take a new snapshot only when future devboxes should
|
|
138
|
+
inherit it. For a member project, ask a team admin to update the Team Template
|
|
139
|
+
when the shared baseline should change.
|
|
127
140
|
|
|
128
141
|
Do not assume changes made on a devbox automatically update the Template box or
|
|
129
142
|
other devboxes. Move or merge finished work intentionally.
|
|
@@ -18,11 +18,11 @@ The workbench has a few persistent areas:
|
|
|
18
18
|
a Template box or devbox is selected, and ends with the
|
|
19
19
|
Terminal/Files/Git/Review/Browser pane control as icon-only buttons that show
|
|
20
20
|
their names on hover; update notices appear in the middle when available.
|
|
21
|
-
- The left pane lists threads, integrations, automations, Project URLs,
|
|
22
|
-
|
|
23
|
-
a Help button stay pinned at the bottom.
|
|
24
|
-
- The detail pane shows the selected thread, Project settings,
|
|
25
|
-
|
|
21
|
+
- The left pane lists threads, integrations, automations, Project URLs, an
|
|
22
|
+
expandable Settings section, and the Template box when that project has one.
|
|
23
|
+
Your account identity and a Help button stay pinned at the bottom.
|
|
24
|
+
- The detail pane shows the selected thread, Project settings, an integration,
|
|
25
|
+
an automation editor, or the Template box page when available.
|
|
26
26
|
- The Terminal, Files, Git/Review, and Browser panes can be shown next to the
|
|
27
27
|
agent pane; Files, Git/Review, and Browser can also pop out into
|
|
28
28
|
near-full-window overlays.
|
|
@@ -124,8 +124,10 @@ row to return it to the default.
|
|
|
124
124
|
## Project Selector
|
|
125
125
|
|
|
126
126
|
Use the project selector in the titlebar to switch between projects on the same
|
|
127
|
-
desktop app account.
|
|
128
|
-
|
|
127
|
+
desktop app account. Threads and devboxes are shown for the selected project.
|
|
128
|
+
Most projects have one Template box. A project created through a Team
|
|
129
|
+
Template's **Member projects** mode has no personal Template box and omits that
|
|
130
|
+
section without changing its normal thread and devbox workflow.
|
|
129
131
|
|
|
130
132
|
Use **New project...** in the project selector to add another project. On
|
|
131
133
|
macOS, **File > New Project...** does the same thing.
|
|
@@ -133,13 +135,15 @@ macOS, **File > New Project...** does the same thing.
|
|
|
133
135
|
Project settings, integrations, automations, and a teammate's shared thread do
|
|
134
136
|
not select one of your Template boxes or devboxes. On those pages, machine
|
|
135
137
|
status and workspace tools are hidden and the workbench does not wake the
|
|
136
|
-
machine you last used. Return to one of your own threads or
|
|
137
|
-
when you want runtime controls and Files,
|
|
138
|
-
Ports.
|
|
138
|
+
machine you last used. Return to one of your own runtime-backed threads or, when
|
|
139
|
+
available, the Template box when you want runtime controls and Files,
|
|
140
|
+
Git/Review, Terminal, Browser, or Ports.
|
|
139
141
|
|
|
140
142
|
The app menu also includes **Project settings**, **Desktop app settings...**,
|
|
141
143
|
**Configure agents...**, **Sign Out**, update actions, and **Show Workbench**.
|
|
142
|
-
|
|
144
|
+
Configure agents can save multiple Codex and Claude accounts or API keys and
|
|
145
|
+
choose one active credential for each agent across all devboxes. The File menu
|
|
146
|
+
also includes **Delete This Project**.
|
|
143
147
|
|
|
144
148
|
## Runtime Status
|
|
145
149
|
|
|
@@ -162,13 +166,13 @@ runtime has no live metrics.
|
|
|
162
166
|
|
|
163
167
|
## Project Settings
|
|
164
168
|
|
|
165
|
-
Expand **Settings**
|
|
166
|
-
settings that belong to the project rather than to a
|
|
167
|
-
page contains **Project storage**, **Git**, **Agent
|
|
168
|
-
devboxes**, and **Devbox lifecycle**, including the
|
|
169
|
-
action, commit thread-link behavior, startup script,
|
|
170
|
-
inactivity behavior, and other new-devbox defaults.
|
|
171
|
-
or wake
|
|
169
|
+
Expand **Settings** near the bottom of the project thread list and open
|
|
170
|
+
**Project settings** for settings that belong to the project rather than to a
|
|
171
|
+
particular machine. This page contains **Project storage**, **Git**, **Agent
|
|
172
|
+
permissions for new devboxes**, and **Devbox lifecycle**, including the
|
|
173
|
+
project's preferred Git action, commit thread-link behavior, startup script,
|
|
174
|
+
shared agent guidance, inactivity behavior, and other new-devbox defaults.
|
|
175
|
+
Opening it does not select or wake a machine.
|
|
172
176
|
|
|
173
177
|
The same Settings section opens **Desktop app settings...** and **Configure
|
|
174
178
|
agents...** in separate windows. Desktop app settings contains only preferences
|
|
@@ -178,9 +182,11 @@ log-out actions without mixing those controls into project settings.
|
|
|
178
182
|
|
|
179
183
|
## Template box
|
|
180
184
|
|
|
181
|
-
|
|
182
|
-
manage snapshots, repositories, maintenance, or
|
|
183
|
-
terminal, inspect files or Git, or check whether
|
|
185
|
+
For a project that has one, the Template box page is for the project's exact
|
|
186
|
+
Template machine. Use it to manage snapshots, repositories, maintenance, or
|
|
187
|
+
the machine itself; open its terminal, inspect files or Git, or check whether
|
|
188
|
+
it is awake. Team Template member projects omit the page and its thread,
|
|
189
|
+
snapshot, repository, terminal, and power controls.
|
|
184
190
|
|
|
185
191
|
Use the terminal button in the Template box header to replace the Template box
|
|
186
192
|
page with its terminal in the main pane. While it is there, Terminal is
|
|
@@ -221,18 +221,29 @@ use the connected user's credential after boxes.dev verifies that the exact
|
|
|
221
221
|
repository was selected for the project and the user still has write access.
|
|
222
222
|
If access stops, reconnect the GitHub account used for the project, use
|
|
223
223
|
**Manage repos** to give the boxes.dev App access, or restore the connected
|
|
224
|
-
user's write permission as directed by the error.
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
224
|
+
user's write permission as directed by the error. When an organization cannot
|
|
225
|
+
approve the App for that repository, **Integrations → GitHub → Use personal
|
|
226
|
+
access** can authorize the official GitHub CLI instead. That personal access
|
|
227
|
+
can authenticate an existing, exact token-free HTTPS project remote after
|
|
228
|
+
boxes.dev confirms that the connected user still has write access. It does not
|
|
229
|
+
convert an SSH remote to HTTPS or change any repository remote.
|
|
230
|
+
|
|
231
|
+
GitHub authenticates the push as the connected user while the commit keeps its
|
|
232
|
+
normal author and committer metadata. Automatic access can push changes under
|
|
233
|
+
`.github/workflows` when the active credential has the required permission.
|
|
234
|
+
Setup defaults to automatic access for GitHub origins; while App approval is
|
|
235
|
+
pending, setup keeps that choice selected and offers the exact approval link or
|
|
236
|
+
the explicit SSH alternative. Existing automatic-access projects can still
|
|
237
|
+
perform ordinary Git operations while approval is pending.
|
|
233
238
|
|
|
234
239
|
## Adding And Reviewing Project Repositories
|
|
235
240
|
|
|
241
|
+
The Template-box repository controls in this section apply to ordinary
|
|
242
|
+
projects. A Team Template member project's tracked repositories come from the
|
|
243
|
+
Team Template's current saved version. Members can use Git/Review on an assigned
|
|
244
|
+
devbox, but cannot change the shared source or add a repository for future
|
|
245
|
+
devboxes from their project.
|
|
246
|
+
|
|
236
247
|
For a direct-child multi-repository project that already uses automatic GitHub
|
|
237
248
|
HTTPS access, open the Template box page and expand **Repositories** after
|
|
238
249
|
**Snapshots**. **Add from GitHub** opens the current GitHub inventory and lets
|
|
@@ -290,7 +301,7 @@ but cannot add another repository at the project root.
|
|
|
290
301
|
## Git Author Identity
|
|
291
302
|
|
|
292
303
|
Account settings has one **Git identity** name and email that boxes.dev can
|
|
293
|
-
carry to the member's Template boxes and devboxes. Saving it is explicit:
|
|
304
|
+
carry to the member's ordinary Template boxes and all assigned devboxes. Saving it is explicit:
|
|
294
305
|
boxes.dev does not infer or save commit authorship from the account profile,
|
|
295
306
|
login email, or connected GitHub account.
|
|
296
307
|
|
|
@@ -315,9 +326,13 @@ access**. Keep it selected to let terminal commands and coding agents use `gh`,
|
|
|
315
326
|
or clear it before continuing to turn the grant back off. Later, open
|
|
316
327
|
**Integrations → GitHub** to change the account-wide choice at any time.
|
|
317
328
|
Commands such as `gh pr`, `gh run`, and `gh api` use the connected user's
|
|
318
|
-
identity
|
|
319
|
-
user and the
|
|
320
|
-
|
|
329
|
+
identity. boxes.dev prefers GitHub App access and limits it to repositories
|
|
330
|
+
available to both that user and the App. If the App cannot access one of the
|
|
331
|
+
project's repositories, **Use personal access** authorizes the official GitHub
|
|
332
|
+
CLI once and makes that access available to the user's boxes.dev machines.
|
|
333
|
+
Personal access is used only for project repositories the App cannot reach and
|
|
334
|
+
still follows the connected user's GitHub permissions. GitHub Actions log
|
|
335
|
+
commands also require the connection's Actions permission.
|
|
321
336
|
|
|
322
337
|
For a GitHub-backed project, **Integrations → GitHub** also checks whether the
|
|
323
338
|
boxes.dev GitHub App can access that project's repositories. If access is
|
|
@@ -325,25 +340,34 @@ missing, the page names the affected repository and opens the applicable
|
|
|
325
340
|
GitHub grant or management flow. Request or add the repository there, then
|
|
326
341
|
return to boxes.dev for an automatic recheck or choose **Check again**. An
|
|
327
342
|
organization admin may need to approve the request. Reconnect GitHub only when
|
|
328
|
-
the page says the account connection needs it.
|
|
343
|
+
the page says the account connection needs it. If App approval is unavailable,
|
|
344
|
+
choose **Use personal access**, copy the one-time code, and approve the official
|
|
345
|
+
GitHub CLI on GitHub. The GitHub App remains the preferred route because App
|
|
346
|
+
access preserves webhook-driven features and can be limited to selected
|
|
347
|
+
repositories. Personal access supports GitHub CLI, eligible HTTPS Git, and
|
|
348
|
+
explicit pull-request actions, but it does not add App webhook delivery for a
|
|
349
|
+
repository the App cannot access. You can disconnect personal access without
|
|
350
|
+
disconnecting the main GitHub connection.
|
|
329
351
|
|
|
330
352
|
This setting is separate from automatic Git pull/push access. It does not
|
|
331
353
|
change repository remotes, switch a project between HTTPS and SSH, or affect
|
|
332
354
|
commit authorship. When the setting is off, or GitHub is not connected to
|
|
333
355
|
boxes.dev, `gh` stays in ordinary user-managed mode and uses the CLI's existing
|
|
334
356
|
local configuration and environment. When the setting is on, boxes.dev manages
|
|
335
|
-
the CLI identity
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
357
|
+
the CLI identity after confirming access to every known repository in the
|
|
358
|
+
current project; do not run `gh auth login`, `gh auth logout`, or another
|
|
359
|
+
`gh auth` command that changes that managed account. A project with missing App
|
|
360
|
+
access stays in ordinary machine-local mode even while the account-wide choice
|
|
361
|
+
is on. Aliases and extensions run as ordinary code owned by the same machine
|
|
362
|
+
user and can use the effective managed or local identity.
|
|
339
363
|
|
|
340
364
|
Open **Project settings** in the desktop app, then expand **Git** to choose the
|
|
341
365
|
project's Preferred Git action. Create a pull request keeps Create PR as the
|
|
342
366
|
usual primary action. Push directly makes the applicable Push or Publish action
|
|
343
|
-
primary instead. The preference applies to
|
|
344
|
-
|
|
345
|
-
they are valid, while repository capabilities, working-tree
|
|
346
|
-
existing-pull-request actions can still take precedence.
|
|
367
|
+
primary instead. The preference applies to every Template box and devbox that
|
|
368
|
+
belongs to the project and changes ordering only: both workflows remain
|
|
369
|
+
available whenever they are valid, while repository capabilities, working-tree
|
|
370
|
+
actions, and existing-pull-request actions can still take precedence.
|
|
347
371
|
|
|
348
372
|
The same settings page has **Add thread links to commits**, which is off by
|
|
349
373
|
default. When enabled, commits created from Git/Review while one of your
|
|
@@ -16,22 +16,26 @@ Use a devbox for normal coding work:
|
|
|
16
16
|
- Slack, Linear, or automation-triggered work.
|
|
17
17
|
|
|
18
18
|
A devbox gives the task its own machine. The agent can edit files, run commands,
|
|
19
|
-
start services, use ports, and test without disturbing the
|
|
20
|
-
devboxes.
|
|
19
|
+
start services, use ports, and test without disturbing the reusable project
|
|
20
|
+
source or other devboxes.
|
|
21
21
|
|
|
22
|
-
|
|
23
|
-
future devboxes inherit.
|
|
22
|
+
In an ordinary project, use the Template box only when the work should change
|
|
23
|
+
the shared baseline that future devboxes inherit. Team Template member projects
|
|
24
|
+
have no personal Template box; team admins maintain their source through the
|
|
25
|
+
Team Template.
|
|
24
26
|
|
|
25
27
|
## Creating A New Devbox + Thread
|
|
26
28
|
|
|
27
29
|
Start from **New devbox + thread** in the desktop thread list. Choose the agent,
|
|
28
|
-
then send the first prompt.
|
|
30
|
+
then send the first prompt. In an ordinary project, the devbox starts from the
|
|
31
|
+
latest verified Template box snapshot. In a Team Template member project, it
|
|
32
|
+
starts from the Team Template's current saved version.
|
|
29
33
|
|
|
30
|
-
If
|
|
34
|
+
If an ordinary project's Template box already has a snapshot, the default creation flow uses the
|
|
31
35
|
latest snapshot. If no snapshot exists, boxes.dev may offer to take the first
|
|
32
36
|
snapshot and then create the devbox.
|
|
33
37
|
|
|
34
|
-
If
|
|
38
|
+
If an ordinary project's Template box has changed in a way future devboxes should inherit, take a
|
|
35
39
|
new snapshot before starting the devbox.
|
|
36
40
|
|
|
37
41
|
To configure startup behavior, open **Project settings** in the desktop app and
|
|
@@ -108,13 +112,17 @@ conversation work.
|
|
|
108
112
|
|
|
109
113
|
## Starting Snapshots For New Devboxes
|
|
110
114
|
|
|
111
|
-
|
|
115
|
+
For an ordinary project, manage snapshots from the Template box page before starting devbox
|
|
112
116
|
work. Take a new snapshot when setup, dependencies, database state, or running
|
|
113
117
|
services changed and the new devbox should inherit that state.
|
|
114
118
|
|
|
115
|
-
On mobile, creating
|
|
119
|
+
On mobile, creating an ordinary-project devbox may let you choose between the latest available
|
|
116
120
|
Template box snapshot and a fresh snapshot taken before the devbox is created.
|
|
117
121
|
|
|
122
|
+
A Team Template member project has no member-controlled snapshot choice. New
|
|
123
|
+
devboxes use the current saved Team Template version, which team admins maintain
|
|
124
|
+
separately.
|
|
125
|
+
|
|
118
126
|
## Moving A Thread From The Template box To A New Devbox
|
|
119
127
|
|
|
120
128
|
Eligible Template box threads can be moved to a new devbox. This is useful when
|
|
@@ -149,6 +157,24 @@ archiving a secondary thread only hides that child thread from the active devbox
|
|
|
149
157
|
group until it is unarchived. If the archived child was selected, desktop opens
|
|
150
158
|
the most recent remaining thread on that same devbox.
|
|
151
159
|
|
|
160
|
+
## Branching A Conversation Onto A New Devbox
|
|
161
|
+
|
|
162
|
+
Use **Continue in new chat** on a completed Codex or Claude response when the
|
|
163
|
+
new work should keep the conversation up to that point. Choose **Current box**
|
|
164
|
+
to branch only the conversation, or **New devbox** to branch both the
|
|
165
|
+
conversation and its machine state.
|
|
166
|
+
|
|
167
|
+
**New devbox** takes a fresh snapshot of the selected thread's exact Template
|
|
168
|
+
box or devbox. It preserves that box's current files and runtime state, then
|
|
169
|
+
restores the snapshot into an independent devbox before creating the child
|
|
170
|
+
conversation there. Managed Codex and Claude work must be idle for the copy;
|
|
171
|
+
boxes.dev retries when an active turn or queued agent work is still settling.
|
|
172
|
+
|
|
173
|
+
This action differs from moving a Template box thread: the original thread
|
|
174
|
+
stays on its source box, and the child starts on the new devbox. It also differs
|
|
175
|
+
from starting an unrelated new thread, because the child retains the selected
|
|
176
|
+
conversation history and native fork ancestry.
|
|
177
|
+
|
|
152
178
|
## Working Inside The Devbox
|
|
153
179
|
|
|
154
180
|
While a devbox is selected:
|
|
@@ -191,7 +217,7 @@ Test work on the selected devbox:
|
|
|
191
217
|
- ask the agent for screenshots or other proof when visual behavior matters.
|
|
192
218
|
|
|
193
219
|
Port forwarding follows the selected runtime, so selecting a different devbox or
|
|
194
|
-
|
|
220
|
+
an ordinary project's Template box changes which running app the port menu opens.
|
|
195
221
|
|
|
196
222
|
## Finishing Work On A Devbox
|
|
197
223
|
|
|
@@ -292,11 +318,12 @@ types must finish or be stopped before the devbox can be destroyed.
|
|
|
292
318
|
Destroying a devbox does not automatically save code to the Template box or to
|
|
293
319
|
Git. Commit, push, merge, download, or otherwise save anything important first.
|
|
294
320
|
The archived transcripts remain readable without a running machine. To
|
|
295
|
-
continue one, choose **Restore thread
|
|
296
|
-
the latest verified project snapshot or
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
321
|
+
continue one, choose **Restore thread**. An ordinary project can restore to a new
|
|
322
|
+
devbox from the latest verified project snapshot or to its current Template
|
|
323
|
+
box. A Team Template member project restores only to a new devbox from the
|
|
324
|
+
current saved Team Template version. The available destination returns the
|
|
325
|
+
thread directly to the normal thread list. Restoring a thread restores its
|
|
326
|
+
conversation, not the destroyed devbox's filesystem or working tree.
|
|
300
327
|
|
|
301
328
|
If the devbox has a child draft with unsent text, boxes.dev blocks destruction
|
|
302
329
|
until that draft is opened and discarded.
|