@boxes-dev/dvb-runtime 1.0.963 → 1.0.965
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
|
@@ -1,16 +1,19 @@
|
|
|
1
1
|
# Team Templates
|
|
2
2
|
|
|
3
3
|
Use this doc for questions about a team's shared starting environments, Team
|
|
4
|
-
Template
|
|
4
|
+
Template saved versions, taking control, or creating a project from a Team
|
|
5
|
+
Template.
|
|
5
6
|
|
|
6
7
|
## What The Team Template Is
|
|
7
8
|
|
|
8
9
|
A Team Template is one named, team-wide starting environment for new projects.
|
|
9
|
-
It is separate from
|
|
10
|
+
It is separate from each ordinary project's Template box. A team can keep
|
|
10
11
|
several Team Templates for different project shapes—for example, a website
|
|
11
12
|
playground, a full-stack application, and backend services. Each Team Template
|
|
12
|
-
has
|
|
13
|
-
an independent
|
|
13
|
+
has one latest saved version. The ordinary creation path gives a new project
|
|
14
|
+
an independent Template box copied from that version. The optional **Member
|
|
15
|
+
projects** mode instead gives the member no Template box and uses the Team
|
|
16
|
+
Template's current saved version for each future devbox.
|
|
14
17
|
|
|
15
18
|
This is useful for employee onboarding, shared company tools, and getting a
|
|
16
19
|
teammate onto boxes.dev without requiring a repository or prepared local
|
|
@@ -19,29 +22,37 @@ environment.
|
|
|
19
22
|
## Who Can Do What
|
|
20
23
|
|
|
21
24
|
Any current team member can inspect the team's available Team Templates. A
|
|
22
|
-
member can create
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
25
|
+
member can create an ordinary project from a template only when it has a saved
|
|
26
|
+
version. Member-project creation also requires an admin to enable it on that
|
|
27
|
+
Team Template. Only team admins can enable Team Templates for the team; create,
|
|
28
|
+
rename, archive, or restore them; edit them; save new versions; use an older
|
|
29
|
+
version; or remove an older version.
|
|
26
30
|
|
|
27
31
|
Only one admin edits a particular Team Template at a time. Different Team
|
|
28
32
|
Templates have independent editing locks, so an admin can prepare more than one
|
|
29
|
-
without crossing their files or
|
|
33
|
+
without crossing their files or version history. An editing session remains
|
|
30
34
|
assigned to its admin if the desktop app closes or the machine sleeps.
|
|
31
35
|
|
|
36
|
+
The saved environment is separate from every admin editing session. After a
|
|
37
|
+
successful save, boxes.dev keeps the cleaned environment asleep as the shared
|
|
38
|
+
source for later editing sessions and member-project devboxes. It is not a
|
|
39
|
+
Template box that admins or members can open. Discarding an editing session
|
|
40
|
+
therefore removes only that unsaved session and never changes the shared saved
|
|
41
|
+
environment.
|
|
42
|
+
|
|
32
43
|
An admin can create multiple Codex and Claude threads directly in the Team
|
|
33
44
|
Template editor. These threads belong to the Team Template definition, not its
|
|
34
45
|
temporary editing machine. They are private to the admin who created them for
|
|
35
46
|
now. Agent credentials, native session files, and other private agent state are
|
|
36
47
|
kept outside the Team Template's authored filesystem and are never copied into
|
|
37
|
-
a
|
|
48
|
+
a saved version or a project created from it.
|
|
38
49
|
|
|
39
50
|
## Finding And Managing Team Templates
|
|
40
51
|
|
|
41
|
-
Open **Team Templates** from the desktop
|
|
52
|
+
Open **Team Templates** from the desktop account menu or **Manage team**. The
|
|
42
53
|
collection shows each named template separately, including its description,
|
|
43
|
-
machine size,
|
|
44
|
-
archived templates here.
|
|
54
|
+
machine size, latest saved version, and editing status. Team admins can also
|
|
55
|
+
reveal archived templates here.
|
|
45
56
|
|
|
46
57
|
Admins create a Team Template from this collection. The default flow starts
|
|
47
58
|
from GitHub: choose one or several existing repositories, or create a new
|
|
@@ -54,15 +65,37 @@ template's card or detail page.
|
|
|
54
65
|
|
|
55
66
|
The template's name and description can change later, but its machine size is
|
|
56
67
|
fixed after creation and is inherited by projects made from it. Creating and
|
|
57
|
-
preparing the entry does not
|
|
58
|
-
the machine and save it first.
|
|
59
|
-
|
|
60
|
-
Open a template's detail page to inspect its
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
or running
|
|
68
|
+
preparing the entry does not create a usable saved version: an admin must
|
|
69
|
+
inspect the machine and save it first.
|
|
70
|
+
|
|
71
|
+
Open a template's detail page to inspect its **Latest saved version** and the
|
|
72
|
+
compact **Previous versions** recovery section. Admins also manage its Project
|
|
73
|
+
defaults, name, description, save cleanup script, **Member projects** settings,
|
|
74
|
+
and archive state there. The detail page is for inspection and administration;
|
|
75
|
+
members start projects from the normal new-project flow instead. Restore an
|
|
76
|
+
archived Team Template before changing its Project defaults or running
|
|
77
|
+
maintenance.
|
|
78
|
+
|
|
79
|
+
The **Member projects** section controls projects whose devboxes use the Team
|
|
80
|
+
Template's current saved files without giving each member a personal Template
|
|
81
|
+
box. Enabling creation requires a current saved version, confirmation that no
|
|
82
|
+
member-specific `.env` or `.env.local` files are needed, and a repository
|
|
83
|
+
inventory with only remote-free, local, or standard `github.com` origins.
|
|
84
|
+
Unsupported network origins remain valid for ordinary Team Template use while
|
|
85
|
+
this mode is unused. Once creation is enabled or linked member projects exist,
|
|
86
|
+
an unsupported origin blocks saving a new current version and identifies only
|
|
87
|
+
the safe repository path and host.
|
|
88
|
+
|
|
89
|
+
Disabling member creation prevents only new projects. Existing linked projects
|
|
90
|
+
may continue to create devboxes and refill their prepared machines. The same
|
|
91
|
+
section defines team-owned startup and teardown scripts for those devboxes.
|
|
92
|
+
These scripts and the current saved files stay live for future machines;
|
|
93
|
+
project behavior settings, Project URLs, and MCP definitions are copied once
|
|
94
|
+
when each member project is created. Template-box setup instructions and
|
|
95
|
+
maintenance do not apply to member projects. Startup can run on warm machines
|
|
96
|
+
kept ready for members, so scripts should avoid unnecessary external side
|
|
97
|
+
effects. Admins see aggregate linked-project and preparation health, never
|
|
98
|
+
member credentials or detailed per-user output.
|
|
66
99
|
|
|
67
100
|
## Project Defaults
|
|
68
101
|
|
|
@@ -72,10 +105,12 @@ Template maintenance and GitHub watches, Git and port behavior, Project URLs,
|
|
|
72
105
|
and project-scoped MCP connections.
|
|
73
106
|
|
|
74
107
|
Each editor saves independently and takes effect immediately for project
|
|
75
|
-
creation. Saving a Project default does not
|
|
108
|
+
creation. Saving a Project default does not save a new filesystem version and
|
|
76
109
|
does not wait for the current editing session to close. Unsaved changes remain
|
|
77
|
-
only in that focused editor; there is no configuration draft,
|
|
78
|
-
history, or rollback. Existing projects never follow later
|
|
110
|
+
only in that focused editor; there is no configuration draft, filesystem save,
|
|
111
|
+
history, or rollback. Existing projects never follow later Project-default
|
|
112
|
+
changes. An ordinary project with its own Template box receives every
|
|
113
|
+
applicable default; the Member-project subset is described above.
|
|
79
114
|
|
|
80
115
|
Project URLs receive fresh hostnames in each new project. MCP defaults contain
|
|
81
116
|
only connection details, never credentials or a Codex/Claude choice. A new
|
|
@@ -95,36 +130,40 @@ the resulting ordinary project afterward.
|
|
|
95
130
|
|
|
96
131
|
Maintenance is real behavior for the Team Template, not only a preset for its
|
|
97
132
|
children. An admin configures its script, schedule, and optional GitHub watches
|
|
98
|
-
under **Project defaults**, or chooses **Run now**. boxes.dev
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
133
|
+
under **Project defaults**, or chooses **Run now**. boxes.dev wakes the clean
|
|
134
|
+
shared saved environment, uses short-lived repository-scoped GitHub App access,
|
|
135
|
+
runs the script, removes those credentials, validates the cleaned result after
|
|
136
|
+
a cold restart, saves it, and makes one new saved version current. A Team
|
|
137
|
+
Template saved before this behavior was available may need one initial restore
|
|
138
|
+
to establish its shared saved environment. A failure preserves the prior saved
|
|
139
|
+
version, discards any machine that may have been partly changed, and never
|
|
140
|
+
modifies an admin's editing session.
|
|
104
141
|
|
|
105
142
|
A maintenance trigger waits behind an active editing session and starts after
|
|
106
143
|
the session closes. Multiple triggers coalesce into the pending run. If the
|
|
107
|
-
script succeeds but
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
144
|
+
script succeeds but saving fails, the detail page offers **Retry save** and
|
|
145
|
+
**Discard result**; retrying the save does not rerun the script. If GitHub App
|
|
146
|
+
access is lost, use **Open GitHub settings** to restore the tracked
|
|
147
|
+
repositories, then choose **Refresh repository access** on the
|
|
111
148
|
maintenance failure before running it again. Repair refreshes only repositories
|
|
112
149
|
the Team Template already tracks; it does not add or replace a repository.
|
|
113
150
|
|
|
114
|
-
|
|
115
|
-
only the saved behavior. Their
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
state are never copied.
|
|
151
|
+
Ordinary projects created with a personal Template box receive an independent
|
|
152
|
+
maintenance policy and watches containing only the saved behavior. Their
|
|
153
|
+
schedules start at the next future occurrence, and enabled watches establish a
|
|
154
|
+
fresh repository baseline without an initial run. Authorization, repository
|
|
155
|
+
baselines, run history, errors, and other live state are never copied. Member
|
|
156
|
+
projects do not copy or run Team Template maintenance; their future devboxes
|
|
157
|
+
use the Team Template's current saved files instead.
|
|
119
158
|
|
|
120
|
-
## Editing And
|
|
159
|
+
## Editing And Saving
|
|
121
160
|
|
|
122
161
|
Open a Team Template, then choose **Take control** to start an editing session.
|
|
123
162
|
The focused, full-window editor uses the same workbench arrangement as a
|
|
124
163
|
project: Team Template threads on the left, the selected Codex or Claude
|
|
125
164
|
conversation in the middle, and the Terminal, Files, Git, or Browser tool on
|
|
126
|
-
the right. Its single titlebar row carries the template name, the source
|
|
127
|
-
|
|
165
|
+
the right. Its single titlebar row carries the template name, the source saved
|
|
166
|
+
version, the session age, the editing machine's status, **Save and close**,
|
|
128
167
|
**Discard**, and the tool switcher. Each column can be resized, and the tool
|
|
129
168
|
pane can be closed or expanded to fill the window; that layout is remembered
|
|
130
169
|
per Team Template. The editor does not create devboxes or offer normal project
|
|
@@ -154,29 +193,37 @@ When editing is finished, choose one of these actions:
|
|
|
154
193
|
|
|
155
194
|
- **Save and close** closes terminal and browser sessions, waits for active
|
|
156
195
|
agent work to settle, saves restorable Team Template threads, removes private
|
|
157
|
-
boxes.dev-managed agent state, runs the team's
|
|
158
|
-
|
|
159
|
-
|
|
196
|
+
boxes.dev-managed agent state, runs the team's save cleanup script if one is
|
|
197
|
+
configured, and queues cleanup, cold-boot validation, and capture for the
|
|
198
|
+
next immutable saved version. The cleaned editing machine becomes the hidden,
|
|
199
|
+
sleeping shared source after the save succeeds. The admin returns to the
|
|
200
|
+
detail page immediately; the prior saved version remains current until the
|
|
201
|
+
new one is ready.
|
|
160
202
|
- **Discard changes** destroys the editing session and keeps the previous
|
|
161
|
-
|
|
203
|
+
saved version unchanged. Active agent work is fenced and restorable threads
|
|
162
204
|
are saved before teardown. The confirmation requires typing `DISCARD`.
|
|
163
205
|
|
|
164
|
-
Members can continue creating projects from
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
206
|
+
Members can continue creating projects from the current saved version while an
|
|
207
|
+
admin edits a future version. Admins can choose **Use this version** for an
|
|
208
|
+
older ready version under **Previous versions**. boxes.dev prepares that saved
|
|
209
|
+
environment in the background and keeps the current version active until the
|
|
210
|
+
older one is ready; the page shows preparation progress or a retryable failure.
|
|
211
|
+
The next save still receives the next version number. Removing an inactive
|
|
212
|
+
version requires a reason, prevents new work from starting from it, and cancels
|
|
213
|
+
project creation still in progress from it. Ordinary projects that already
|
|
214
|
+
received their independent Template box continue to work. Saving, changing the
|
|
215
|
+
current version, removal, and cleanup on one Team Template do not change
|
|
216
|
+
another.
|
|
172
217
|
|
|
173
218
|
## Creating A Project
|
|
174
219
|
|
|
175
|
-
|
|
220
|
+
For an ordinary project with its own Template box, start the ordinary
|
|
221
|
+
new-project flow and choose **Start from a Team Template**.
|
|
176
222
|
Select the exact template, then name the project and choose which coding agents
|
|
177
|
-
should be available. The picker shows only templates with a
|
|
178
|
-
|
|
179
|
-
|
|
223
|
+
should be available. The picker shows only templates with a current saved
|
|
224
|
+
version and does not preselect one. Before creation, the flow shows the
|
|
225
|
+
exact version, machine size, and a read-only summary of the current Project
|
|
226
|
+
defaults.
|
|
180
227
|
|
|
181
228
|
If the Team Template has any GitHub maintenance watch, including a disabled
|
|
182
229
|
watch, project creation requires the member's current boxes.dev GitHub
|
|
@@ -184,22 +231,22 @@ connection and GitHub App access to every watched repository. The flow presents
|
|
|
184
231
|
the existing connect, update-authorization, install, or grant-access action and
|
|
185
232
|
does not allocate the Template box until access is satisfied.
|
|
186
233
|
|
|
187
|
-
When creation starts, boxes.dev pins the selected filesystem
|
|
234
|
+
When creation starts, boxes.dev pins the selected filesystem version and the
|
|
188
235
|
current saved Project defaults as separate inputs. Later Team Template edits do
|
|
189
236
|
not change that in-progress job. boxes.dev creates a normal user-owned Template
|
|
190
237
|
box and makes the project available through the ordinary desktop workbench. It
|
|
191
|
-
never silently substitutes another Team Template or a newer
|
|
238
|
+
never silently substitutes another Team Template or a newer version. **Cancel
|
|
192
239
|
and clean up** removes an unfinished creation. A recoverable failure stays in
|
|
193
240
|
the flow with **Retry creation**, and returning to the same template reattaches
|
|
194
241
|
to its unfinished creation.
|
|
195
242
|
|
|
196
|
-
The new project is independent. Later Team Template
|
|
197
|
-
|
|
243
|
+
The new project is independent. Later Team Template versions, save cleanup, or
|
|
244
|
+
leaving the team do not modify or remove the project's Template box,
|
|
198
245
|
threads, snapshots, or devboxes. Creating it uses a normal project slot and its
|
|
199
246
|
runtime uses the member's normal billing entitlement.
|
|
200
247
|
|
|
201
|
-
Setup instructions are current Project defaults, not part of the
|
|
202
|
-
cadence. If instructions are present and the selected agent is authenticated,
|
|
248
|
+
Setup instructions are current Project defaults, not part of the filesystem
|
|
249
|
+
save cadence. If instructions are present and the selected agent is authenticated,
|
|
203
250
|
boxes.dev starts an optional setup thread after the project and its initial
|
|
204
251
|
snapshot are usable. Project creation is considered complete once that setup
|
|
205
252
|
thread starts; the user can open the project while it continues. The agent is
|
|
@@ -222,15 +269,15 @@ short-lived GitHub App access for those same selected repositories and refreshes
|
|
|
222
269
|
it before expiry. This supports authenticated fetch, pull, and push from
|
|
223
270
|
Terminal or the Git pane without exposing an admin's broader GitHub identity.
|
|
224
271
|
The App token is removed when editing pauses and restored after the admin wakes
|
|
225
|
-
the session; saving removes and verifies all managed Git access before
|
|
272
|
+
the session; saving removes and verifies all managed Git access before version
|
|
226
273
|
capture. GitHub attributes remote operations to the boxes.dev App while Git
|
|
227
274
|
commit author metadata remains unchanged. Pushes that modify GitHub Actions
|
|
228
275
|
workflow files are not supported by this managed access.
|
|
229
276
|
|
|
230
277
|
Existing repositories, remotes, multiple-repository layouts, and submodules
|
|
231
|
-
are copied with the
|
|
232
|
-
project and repository identity instead of the
|
|
233
|
-
identity.
|
|
278
|
+
are copied with the saved version. The destination project receives fresh
|
|
279
|
+
boxes.dev project and repository identity instead of the saving admin's
|
|
280
|
+
project identity.
|
|
234
281
|
|
|
235
282
|
For SSH remotes, and for standard GitHub or GitLab HTTPS remotes, boxes.dev
|
|
236
283
|
generates a fresh SSH key inside the destination Template box. The creation
|
|
@@ -240,34 +287,34 @@ access**. Recognized GitHub and GitLab HTTPS remotes use the verified key after
|
|
|
240
287
|
this step. Generic HTTPS, local, and unusual remotes are preserved; finish any
|
|
241
288
|
host-specific authentication from Terminal or with the setup agent.
|
|
242
289
|
|
|
243
|
-
## Files And Credentials Included In A
|
|
290
|
+
## Files And Credentials Included In A Saved Version
|
|
244
291
|
|
|
245
292
|
Team admins are trusted authors of the shared environment. Saving removes
|
|
246
|
-
boxes.dev-managed runtime identity and session state before
|
|
293
|
+
boxes.dev-managed runtime identity and session state before capture, but it
|
|
247
294
|
does not guess which team-authored files are secrets. Files deliberately left
|
|
248
295
|
in the environment—including `.env` files, databases, shell history, or
|
|
249
|
-
custom SSH and cloud credentials—are copied into
|
|
250
|
-
the
|
|
296
|
+
custom SSH and cloud credentials—are copied into ordinary projects and into
|
|
297
|
+
member-project devboxes that use the saved version.
|
|
251
298
|
|
|
252
299
|
The short-lived GitHub App token used during setup is removed after cloning.
|
|
253
300
|
The separate short-lived token used during editing is removed on pause and
|
|
254
|
-
before
|
|
255
|
-
admin installs manually.
|
|
301
|
+
before saved-version capture. This does not cover SSH keys or credentials that
|
|
302
|
+
an admin installs manually.
|
|
256
303
|
|
|
257
|
-
Review the editing session and the save warning before
|
|
258
|
-
|
|
304
|
+
Review the editing session and the save warning before saving. Configure a
|
|
305
|
+
save cleanup script in the template's settings when the team intentionally
|
|
259
306
|
wants to remove additional team-authored state. It runs after boxes.dev removes
|
|
260
|
-
its own managed state; a nonzero exit stops the save instead of
|
|
261
|
-
partially cleaned
|
|
307
|
+
its own managed state; a nonzero exit stops the save instead of creating a
|
|
308
|
+
partially cleaned version.
|
|
262
309
|
|
|
263
310
|
## Taking Over A Sleeping Edit
|
|
264
311
|
|
|
265
312
|
Another admin cannot enter the current admin's raw editing session. If one Team
|
|
266
313
|
Template's editing session is asleep, the next admin must choose **Resolve**
|
|
267
314
|
and explicitly save or discard that work first. Saving makes the sleeping
|
|
268
|
-
admin's work the next
|
|
269
|
-
unsaved work and keeps the
|
|
270
|
-
editing session for the new admin from the chosen
|
|
315
|
+
admin's work the next saved version; discarding permanently destroys their
|
|
316
|
+
unsaved work and keeps the latest saved version. boxes.dev then creates a fresh
|
|
317
|
+
editing session for the new admin from the chosen version, so neither admin
|
|
271
318
|
enters the other's session. A command already running through the current
|
|
272
319
|
holder's selected project Template box must finish or be interrupted before
|
|
273
320
|
another admin can take over that template. Other Team Templates remain
|
|
@@ -55,15 +55,17 @@ GitHub CLI authentication is an explicit user choice in **Finalize Bundle →
|
|
|
55
55
|
GitHub access** during first-run desktop setup for supported GitHub repositories
|
|
56
56
|
and remains manageable from **Integrations → GitHub → GitHub CLI in devboxes**.
|
|
57
57
|
Connecting or reconnecting GitHub turns it on by default; clear the setup
|
|
58
|
-
checkbox or turn off the Integrations setting to disable it. When enabled
|
|
58
|
+
checkbox or turn off the Integrations setting to disable it. When enabled and
|
|
59
|
+
the App credential can access every known repository in the current project,
|
|
59
60
|
ordinary `gh` commands and agent workflows can use the connected GitHub
|
|
60
|
-
identity. While
|
|
61
|
-
refresh`, or `gh auth switch`, and do not add another
|
|
62
|
-
disabled,
|
|
63
|
-
|
|
64
|
-
ordinary
|
|
65
|
-
|
|
66
|
-
|
|
61
|
+
identity. While managed access is effective, do not run `gh auth login`, `gh
|
|
62
|
+
auth logout`, `gh auth refresh`, or `gh auth switch`, and do not add another
|
|
63
|
+
ambient GitHub token. When disabled, GitHub is not connected to boxes.dev, or a
|
|
64
|
+
known project repository is unavailable to the App credential, `gh` uses the
|
|
65
|
+
user's ordinary machine-local configuration and environment. Aliases and
|
|
66
|
+
extensions run as ordinary same-user code with the effective managed or local
|
|
67
|
+
identity, so install only ones the user trusts. This CLI grant is separate from
|
|
68
|
+
the project's Git remote and automatic pull/push access.
|
|
67
69
|
|
|
68
70
|
## Managing Project Repositories
|
|
69
71
|
|
|
@@ -8,7 +8,8 @@ threads in boxes.dev.
|
|
|
8
8
|
A thread is a conversation with a coding agent connected to a runtime. A thread
|
|
9
9
|
can run on:
|
|
10
10
|
|
|
11
|
-
- the Template box, for setup, maintenance, and shared baseline work
|
|
11
|
+
- the Template box, for setup, maintenance, and shared baseline work in a
|
|
12
|
+
project that has one;
|
|
12
13
|
- a new devbox, for ordinary task work;
|
|
13
14
|
- an existing devbox, when starting another thread inside a devbox that already
|
|
14
15
|
exists.
|
|
@@ -22,9 +23,11 @@ than separate agent choices.
|
|
|
22
23
|
Start threads from the desktop thread list.
|
|
23
24
|
|
|
24
25
|
Use **New devbox + thread** for most work. A devbox thread gives the task its
|
|
25
|
-
own isolated machine.
|
|
26
|
-
|
|
27
|
-
|
|
26
|
+
own isolated machine. In an ordinary project, this uses the latest Template-box
|
|
27
|
+
snapshot when one is available. In a Team Template member project, it uses the
|
|
28
|
+
Team Template's current saved version and the project's prepared devbox pool.
|
|
29
|
+
If an ordinary project has no snapshot yet, the devbox start control may first
|
|
30
|
+
take one and then create the devbox.
|
|
28
31
|
|
|
29
32
|
Use **New thread** on the Template box only when the work belongs in the shared
|
|
30
33
|
baseline, such as project setup, dependency installation for future devboxes, or
|
|
@@ -36,8 +39,8 @@ new snapshot from the Template box first.
|
|
|
36
39
|
|
|
37
40
|
Threads can also be browsed and started from a terminal with
|
|
38
41
|
`dvb agents [project]`. The project-wide switchboard groups threads by devbox
|
|
39
|
-
and Template box, shows live working/input/unread state, and
|
|
40
|
-
Claude threads on the selected machine or a new devbox. Enter opens the
|
|
42
|
+
and by Template box when available, shows live working/input/unread state, and
|
|
43
|
+
starts Codex or Claude threads on the selected machine or a new devbox. Enter opens the
|
|
41
44
|
thread's terminal interface; leaving that interface returns to the switchboard
|
|
42
45
|
without creating another thread.
|
|
43
46
|
|
|
@@ -90,8 +93,10 @@ event renders.
|
|
|
90
93
|
|
|
91
94
|
The switchboard can pin or unpin eligible Template-box threads and devbox
|
|
92
95
|
anchors with `p`, rename with `r`, and archive or restore with `x`. Restoring a
|
|
93
|
-
cold thread opens a choice between a new devbox from the
|
|
94
|
-
snapshot and the existing Template-box path.
|
|
96
|
+
cold thread in an ordinary project opens a choice between a new devbox from the
|
|
97
|
+
latest project snapshot and the existing Template-box path. A Team Template
|
|
98
|
+
member project restores only to a new devbox from the saved version pinned when
|
|
99
|
+
restore begins. Codex
|
|
95
100
|
archive updates its saved native session first. Claude archive updates the
|
|
96
101
|
shared thread list without waking the machine. Changes appear on desktop and
|
|
97
102
|
in the terminal because both surfaces use the same thread identity and
|
|
@@ -110,6 +115,31 @@ directory before the first prompt is sent. The options are the project
|
|
|
110
115
|
directory and the tracked repo directories in that project. Existing threads
|
|
111
116
|
continue in the working directory they were originally started with.
|
|
112
117
|
|
|
118
|
+
## Continuing In A New Chat
|
|
119
|
+
|
|
120
|
+
On a completed Codex or Claude response, choose **Continue in new chat** and
|
|
121
|
+
then choose where the new conversation should run:
|
|
122
|
+
|
|
123
|
+
- **Current box** branches the conversation at that response and keeps the new
|
|
124
|
+
thread on the same Template box or devbox. Both conversations see the same
|
|
125
|
+
live filesystem and machine state.
|
|
126
|
+
- **New devbox** takes a fresh snapshot of the exact box where the conversation
|
|
127
|
+
currently runs, starts a new devbox from that snapshot, and creates the
|
|
128
|
+
conversation branch there. This includes changes made on an ordinary devbox;
|
|
129
|
+
it does not substitute the project's latest Template box snapshot.
|
|
130
|
+
|
|
131
|
+
**New devbox** waits until managed Codex and Claude work on the source box is
|
|
132
|
+
idle. If an agent is still finishing a turn, has a queued follow-up, or is
|
|
133
|
+
waiting on an agent request, boxes.dev leaves the source unchanged and retries
|
|
134
|
+
the copy. An older source box may need its local boxes.dev service updated
|
|
135
|
+
before this option is available.
|
|
136
|
+
|
|
137
|
+
The copy keeps the new conversation's native Codex or Claude ancestry while
|
|
138
|
+
giving it an independent machine. The source box remains available. If the
|
|
139
|
+
project uses Tailscale, only the copied source box briefly disconnects and
|
|
140
|
+
receives a fresh identity after the snapshot; sibling devboxes stay connected,
|
|
141
|
+
and the destination devbox enrolls with its own identity.
|
|
142
|
+
|
|
113
143
|
## MCP Connections
|
|
114
144
|
|
|
115
145
|
Open **Integrations → MCPs** in the desktop app to manage remote MCP servers in
|
|
@@ -166,6 +196,11 @@ counts. Use **Reauthorize** or **Remove from Codex** / **Remove from Claude**
|
|
|
166
196
|
from an agent chip's menu, and the row's own **⋯** menu to edit the definition
|
|
167
197
|
and headers or to remove the connection entirely.
|
|
168
198
|
|
|
199
|
+
In a Team Template member project, the centrally managed MCP list remains
|
|
200
|
+
available but the **Template-managed MCPs** inventory is omitted because the
|
|
201
|
+
member has no Template box. Each connection keeps its normal per-agent sign-in
|
|
202
|
+
and recovery state.
|
|
203
|
+
|
|
169
204
|
## Plugins
|
|
170
205
|
|
|
171
206
|
Open **Integrations → Codex/Claude Plugins** in the desktop app. The page talks
|
|
@@ -243,6 +278,11 @@ an eligible public GitHub plugin managed for this project; an unsupported source
|
|
|
243
278
|
stays installed only on the current box. The install is never blocked merely
|
|
244
279
|
because boxes.dev cannot manage that plugin type for a project.
|
|
245
280
|
|
|
281
|
+
Team Template member projects omit this project-wide Plugin page in the MVP
|
|
282
|
+
because its native inventory and marketplace actions require a personal
|
|
283
|
+
Template box. A user or agent can still use the agent's native Plugin tooling
|
|
284
|
+
on an exact devbox; that installation is local to that devbox.
|
|
285
|
+
|
|
246
286
|
## Draft And Startup States
|
|
247
287
|
|
|
248
288
|
New threads can appear as drafts before the first prompt is sent. During
|
|
@@ -252,11 +292,11 @@ thread, or sending the first message.
|
|
|
252
292
|
Before a new-devbox draft is assigned its exact devbox, it belongs to the
|
|
253
293
|
project rather than to the Template box. The desktop app keeps runtime status,
|
|
254
294
|
Terminal, Files, Git/Review, Browser, Ports, and machine controls hidden during
|
|
255
|
-
that period. Background preparation can still use the chosen
|
|
256
|
-
|
|
295
|
+
that period. Background preparation can still use the project's chosen
|
|
296
|
+
reusable source; that preparation does not make a Template box or the preparing
|
|
257
297
|
devbox the selected runtime. After placement, those controls follow the exact
|
|
258
|
-
new devbox. A draft explicitly created on
|
|
259
|
-
|
|
298
|
+
new devbox. A draft explicitly created on an available Template box continues
|
|
299
|
+
to select it normally.
|
|
260
300
|
|
|
261
301
|
Leaving a new thread you never touched discards it, so the thread list does not
|
|
262
302
|
collect empty `New thread` rows. A draft is kept as soon as it has something to
|
|
@@ -395,16 +435,19 @@ across turns. Users can start a goal from goal mode or with `/goal ...`, then
|
|
|
395
435
|
edit, pause, resume, replace, or clear it. Goal statuses include Pursuing goal,
|
|
396
436
|
Paused goal, Goal blocked, Goal usage limited, Goal limited, and Goal achieved.
|
|
397
437
|
|
|
398
|
-
An idle Codex thread can be branched into a separate conversation
|
|
399
|
-
|
|
400
|
-
the Split icon beneath a completed desktop agent response to keep
|
|
401
|
-
through that turn. Its tooltip reads **Continue in new chat
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
438
|
+
An idle Codex thread can be branched into a separate conversation. Use exact
|
|
439
|
+
`/fork` to branch from the current tip on the current Template box or devbox.
|
|
440
|
+
Or use the Split icon beneath a completed desktop agent response to keep
|
|
441
|
+
history only through that turn. Its tooltip reads **Continue in new chat**,
|
|
442
|
+
and its menu offers **Current box** and **New devbox**. Current box shares the
|
|
443
|
+
source thread's files and working directory. New devbox snapshots the exact
|
|
444
|
+
Template box or devbox that hosts the source, then creates an independent
|
|
445
|
+
devbox with that filesystem state. This includes the current working tree when
|
|
446
|
+
the source is already a devbox. The source remains unchanged, and the source
|
|
447
|
+
and child can continue independently. Mobile exposes only exact `/fork`, not a
|
|
448
|
+
persistent action on each historical turn. Fork controls are hidden when the
|
|
449
|
+
connected runtime does not support native Codex thread branching and are
|
|
450
|
+
unavailable while the source is working.
|
|
408
451
|
|
|
409
452
|
Codex active turns can usually be interrupted with the Stop button or Escape.
|
|
410
453
|
If interruption has already been requested, the UI shows that the turn is
|
|
@@ -424,15 +467,17 @@ enabled. On desktop, `/model` opens the model picker, and `/model <model>`
|
|
|
424
467
|
switches directly to a known model. Older supported model generations appear
|
|
425
468
|
under **More models** in the picker.
|
|
426
469
|
|
|
427
|
-
An idle Claude chat can continue in a separate chat
|
|
428
|
-
|
|
470
|
+
An idle Claude chat can continue in a separate chat. Use exact `/fork` to
|
|
471
|
+
continue from the current tip on the current Template box or devbox. Or use the
|
|
429
472
|
Split icon beneath a completed desktop response to keep history only through
|
|
430
|
-
that response. Its tooltip reads **Continue in new chat
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
473
|
+
that response. Its tooltip reads **Continue in new chat**, and its menu offers
|
|
474
|
+
**Current box** and **New devbox**. Current box shares the source chat's files
|
|
475
|
+
and working directory. New devbox snapshots the exact Template box or devbox
|
|
476
|
+
that hosts the source, then creates an independent devbox with that filesystem
|
|
477
|
+
state. This includes the current working tree when the source is already a
|
|
478
|
+
devbox. The original chat is unchanged, and both chats can continue
|
|
479
|
+
independently. Mobile exposes only exact `/fork`. These controls appear only
|
|
480
|
+
for managed Claude chats whose connected runtime supports chat forking.
|
|
436
481
|
|
|
437
482
|
Model and reasoning selections belong to the Claude thread. A new
|
|
438
483
|
selection remains associated with that thread while it is applied, and the
|
|
@@ -596,8 +641,8 @@ to finish or use the runtime controls if the whole runtime is stuck.
|
|
|
596
641
|
|
|
597
642
|
## Thread List Organization
|
|
598
643
|
|
|
599
|
-
The desktop thread list groups work by devboxes, automations, and
|
|
600
|
-
threads.
|
|
644
|
+
The desktop thread list groups work by devboxes, automations, and, when the
|
|
645
|
+
project has one, Template-box threads.
|
|
601
646
|
|
|
602
647
|
Thread sections include pinned, recent, and archived chats. Template box pinned
|
|
603
648
|
threads can be reordered. Archived chats can be shown or hidden. Template box
|
|
@@ -626,10 +671,9 @@ present under **Ready to move**. It lists nonzero History only, temporarily
|
|
|
626
671
|
blocked, and already-cold exceptions separately from true job failures.
|
|
627
672
|
|
|
628
673
|
On mobile, the project list shows a spinner while at least one thread in that
|
|
629
|
-
project is running. Its last-activity time and recent ordering include
|
|
630
|
-
|
|
631
|
-
|
|
632
|
-
runtime.
|
|
674
|
+
project is running. Its last-activity time and recent ordering include every
|
|
675
|
+
project thread. Sleeping machine status is omitted from this project-level
|
|
676
|
+
view; open the project to see and control its runtime.
|
|
633
677
|
|
|
634
678
|
## Team Access And Sharing
|
|
635
679
|
|
|
@@ -644,8 +688,8 @@ Team admins choose **Thread access** in Team settings:
|
|
|
644
688
|
|
|
645
689
|
With **Thread titles** or **All threads**, use **Team work** in the desktop
|
|
646
690
|
project selector or mobile Home to choose a teammate's project. Team work
|
|
647
|
-
reuses the familiar devbox,
|
|
648
|
-
read-only form. It does not include a composer, Files, Git/Review, terminal,
|
|
691
|
+
reuses the familiar devbox, thread-list, transcript, and optional Template-box
|
|
692
|
+
layout in read-only form. It does not include a composer, Files, Git/Review, terminal,
|
|
649
693
|
ports, or runtime controls. Opening Team work or a shared transcript does not
|
|
650
694
|
select or wake the viewer's last Template box or devbox. Merely browsing a
|
|
651
695
|
teammate's work does not add it to **Shared with me**.
|
|
@@ -717,8 +761,9 @@ The thread action menu can include:
|
|
|
717
761
|
- Pin thread or Unpin thread.
|
|
718
762
|
- Rename thread.
|
|
719
763
|
- Archive thread or Unarchive thread.
|
|
720
|
-
- Restore thread
|
|
721
|
-
|
|
764
|
+
- Restore thread for an archived cold-storage thread. Ordinary projects offer
|
|
765
|
+
To new devbox and To Template box; Team Template member projects offer only
|
|
766
|
+
To new devbox.
|
|
722
767
|
- Copy transcript, which copies user messages and final agent replies as
|
|
723
768
|
structured Markdown.
|
|
724
769
|
- Copy working directory.
|
|
@@ -741,15 +786,16 @@ lifecycle actions such as New thread, Sleep now, and Destroy and archive.
|
|
|
741
786
|
|
|
742
787
|
Destroy and archive preserves eligible thread history directly in cold storage
|
|
743
788
|
before deleting the devbox. The archived history stays readable without waking
|
|
744
|
-
|
|
745
|
-
|
|
746
|
-
it to the normal thread list. If boxes.dev cannot safely preserve the history
|
|
789
|
+
a machine. Restore an individual thread to a new devbox from the project's
|
|
790
|
+
current reusable source or, in an ordinary project, to the current Template
|
|
791
|
+
box; either path returns it to the normal thread list. If boxes.dev cannot safely preserve the history
|
|
747
792
|
because the devbox connection is unavailable, it keeps the devbox and thread
|
|
748
793
|
and reports the failure instead of deleting the source.
|
|
749
794
|
|
|
750
795
|
## Threads On The Template box Versus Devbox Threads
|
|
751
796
|
|
|
752
|
-
Template box threads are useful for setup and baseline maintenance
|
|
797
|
+
Template box threads are useful for setup and baseline maintenance in projects
|
|
798
|
+
that have a Template box. They can be
|
|
753
799
|
moved to a new devbox later when the thread becomes real task work and the
|
|
754
800
|
current state allows it.
|
|
755
801
|
|