@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.
@@ -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 releases, taking control, or creating a project from a Team 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 every user's project Template boxes. A team can keep
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 its own active, versioned release, and each project created from it receives
13
- an independent copy.
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 a project from a template only when it has an active release.
23
- Only team admins can enable Team Templates for the team; create, rename,
24
- archive, or restore them; edit them; publish releases; make an older release
25
- active; or revoke a release.
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 release history. An editing session remains
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 release or a project created from it.
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 Settings menu or Team Settings. The
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, current release, and editing status. Team admins can also reveal
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 publish a usable release: an admin must inspect
58
- the machine and save it first.
59
-
60
- Open a template's detail page to inspect its active release and release
61
- history. Admins also manage its Project defaults, name, description, release
62
- cleanup script, and archive state there. The detail page is for inspection and
63
- administration; members start projects from the normal new-project flow
64
- instead. Restore an archived Team Template before changing its Project defaults
65
- or running maintenance.
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 publish a filesystem release and
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, publish action,
78
- history, or rollback. Existing projects never follow later changes.
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 restores the
99
- active release into a temporary team-owned maintenance machine with no user
100
- owner or customer billing, uses short-lived repository-scoped GitHub App
101
- access, runs the script, captures and verifies the result, and activates one
102
- new release. A failure preserves the prior active release and never modifies an
103
- admin's editing machine.
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 publication fails, the detail page offers **Retry
108
- publication** and **Discard result**; publication retry does not rerun the
109
- script. If GitHub App access is lost, use **Open GitHub settings** to restore
110
- the tracked repositories, then choose **Refresh repository access** on the
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
- New projects receive an independent maintenance policy and watches containing
115
- only the saved behavior. Their schedules start at the next future occurrence,
116
- and enabled watches establish a fresh repository baseline without an initial
117
- run. Authorization, repository baselines, run history, errors, and other live
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 Publishing
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
- release, the session age, the editing machine's status, **Save and close**,
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 release cleanup script if one
158
- is configured, and captures and verifies the next immutable release before
159
- making it active. Saving continues if the admin closes the window.
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
- active release unchanged. Active agent work is fenced and restorable threads
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 that template's active release
165
- while an admin edits a future release. Admins can also make an older ready
166
- release active again from Release history; the next save still receives the
167
- next version number. Revoking an inactive release requires a reason, prevents
168
- new work from starting from it, and cancels project creation still in progress
169
- from it. Projects that already became independent continue to work. Saving,
170
- making a release active, revocation, and cleanup on one Team Template do not
171
- change another.
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
- Start the ordinary new-project flow and choose **Start from a Team Template**.
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 published active
178
- release and does not preselect one. Before creation, the flow shows the exact
179
- release, machine size, and a read-only summary of the current Project defaults.
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 release and the
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 release. **Cancel
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 releases, release cleanup,
197
- or leaving the team do not modify or remove the project's Template box,
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 release save
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 release
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 release. The destination project receives fresh boxes.dev
232
- project and repository identity instead of the publishing admin's project
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 Release
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 publishing, but it
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 every project created from
250
- the release.
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 release capture. This does not cover SSH keys or credentials that an
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 publishing. Configure a
258
- release cleanup script in the template's settings when the team intentionally
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 publishing a
261
- partially cleaned release.
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 active release; discarding permanently destroys their
269
- unsaved work and keeps the current release. boxes.dev then creates a fresh
270
- editing session for the new admin from the chosen release, so neither admin
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 enabled, do not run `gh auth login`, `gh auth logout`, `gh auth
61
- refresh`, or `gh auth switch`, and do not add another ambient GitHub token. When
62
- disabled, or when GitHub is not connected to boxes.dev, `gh` uses the user's
63
- ordinary local configuration and environment. Aliases and extensions run as
64
- ordinary same-user code with the managed identity, so install only ones the
65
- user trusts. This CLI grant is separate from the project's Git remote and
66
- automatic pull/push access.
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. Every desktop action with this label uses the latest
26
- Template box snapshot when one is available. If no snapshot exists yet, the
27
- devbox start control may first take a snapshot and then create the devbox.
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 starts Codex or
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 latest project
94
- snapshot and the existing Template-box path. Codex
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 Template box
256
- snapshot; that preparation does not make the Template box or the preparing
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 the Template box continues to select
259
- the Template box normally.
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 on the same
399
- Template box or devbox. Use exact `/fork` to branch from the current tip, or use
400
- the Split icon beneath a completed desktop agent response to keep history only
401
- through that turn. Its tooltip reads **Continue in new chat**.
402
- Mobile exposes only exact `/fork`, not a persistent action on each historical
403
- turn. A conversation fork creates a new Codex thread, not a new devbox,
404
- worktree, or snapshot. The source remains unchanged, and the source and child
405
- can continue independently. Fork controls are hidden when the connected
406
- runtime does not support native Codex thread branching and are unavailable
407
- while the source is working.
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 on the same Template
428
- box or devbox. Use exact `/fork` to continue from the current tip, or use the
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**. Mobile exposes only
431
- exact `/fork`. The new chat shares the same files and working directory; this
432
- does not create or rewind a devbox, worktree, or snapshot. The original chat is
433
- unchanged, and both chats can continue independently. These controls appear
434
- only for managed Claude chats whose connected runtime supports chat
435
- forking.
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 Template box
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 threads
630
- on both the Template box and the project's devboxes. Sleeping machine status is
631
- omitted from this project-level view; open the project to see and control its
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, Template box, thread-list, and transcript layout in
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, with To new devbox and To Template box destinations, for an
721
- archived cold-storage thread.
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
- the Template box. Restore an individual thread to a new devbox from the latest
745
- verified project snapshot or to the current Template box; either path returns
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. They can be
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