@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.
@@ -6,25 +6,32 @@ detailed feature docs.
6
6
 
7
7
  ## Where Setup Leaves You
8
8
 
9
- After setup, the desktop app opens onto your project workbench. The project has
10
- a Template box, which is the persistent base machine for that project. Setup
11
- also starts a setup thread on the Template box. That thread is useful for
12
- questions about what setup did, what still needs attention, or how the base
13
- environment should be adjusted.
9
+ After setup, the desktop app opens onto your project workbench. Most projects
10
+ have a Template box: the persistent base machine for that project. Their setup
11
+ also starts a setup thread there for questions about what setup did, what still
12
+ needs attention, or how the base environment should be adjusted.
13
+
14
+ A project created from a Team Template in **Member projects** mode has no
15
+ personal Template box or setup thread. Team admins maintain the shared Team
16
+ Template, and every new devbox starts from its current saved files. In normal
17
+ use, the project otherwise works like any other project: its threads,
18
+ automations, integrations, Project URLs, settings, and devboxes still belong to
19
+ the member.
14
20
 
15
21
  Most day-to-day coding work should happen in user-started threads. For feature
16
22
  work, bug fixes, refactors, and experiments, create a new devbox + thread. A
17
23
  devbox gives the agent an isolated copy of the project state so it can edit,
18
24
  run, test, and iterate without disturbing the Template box.
19
25
 
20
- Use the Template box for the stable project baseline: checking that the app
21
- runs, taking snapshots, maintaining shared project setup, and asking
22
- setup-oriented questions. Use devboxes for task work.
26
+ In a project with a Template box, use it for the stable project baseline:
27
+ checking that the app runs, taking snapshots, maintaining shared project
28
+ setup, and asking setup-oriented questions. In every project, use devboxes for
29
+ normal task work.
23
30
 
24
31
  ## First Things To Check
25
32
 
26
- Start by selecting the Template box in the desktop app and confirming the
27
- project looks healthy:
33
+ For a project with a Template box, start by selecting it in the desktop app and
34
+ confirming the project looks healthy:
28
35
 
29
36
  - Open the terminal pane if you want to inspect the environment or run commands.
30
37
  - Use the ports menu to open any running local app or copied forwarded URL.
@@ -36,32 +43,39 @@ If the project does not run yet, stay on the Template box and ask the setup
36
43
  thread to help finish setup. After the Template box is healthy, create devboxes
37
44
  for ordinary coding tasks.
38
45
 
46
+ For a Team Template member project, project creation checks required GitHub
47
+ access and prepares a devbox before **Open project** becomes available. After
48
+ opening it, start a new devbox + thread; any remaining optional setup problem
49
+ appears as a warning with its own recovery action.
50
+
39
51
  ## Recommended Workflow
40
52
 
41
53
  The recommended boxes.dev workflow is:
42
54
 
43
- 1. Keep the Template box as the clean working baseline for the project.
44
- 2. Take a snapshot of the Template box when it is in a state worth reusing.
45
- 3. Create a new devbox + thread for each meaningful task.
46
- 4. Let the agent edit code, run commands, and test inside that devbox.
47
- 5. Review the files and git changes from the desktop app.
48
- 6. Use forwarded ports to manually test any running app on the selected devbox.
49
- 7. When the work is ready, commit, push, merge, or move the changes using the
55
+ 1. For a project with a Template box, keep it as the clean baseline and take a
56
+ snapshot when its state is worth reusing. Team Template member projects use
57
+ the shared saved files maintained by team admins instead.
58
+ 2. Create a new devbox + thread for each meaningful task.
59
+ 3. Let the agent edit code, run commands, and test inside that devbox.
60
+ 4. Review the files and git changes from the desktop app.
61
+ 5. Use forwarded ports to manually test any running app on the selected devbox.
62
+ 6. When the work is ready, commit, push, merge, or move the changes using the
50
63
  workflow your project uses.
51
- 8. Sleep or destroy devboxes you no longer need so they stop using awake devbox
64
+ 7. Sleep or destroy devboxes you no longer need so they stop using awake devbox
52
65
  capacity.
53
66
 
54
67
  ## Desktop App Orientation
55
68
 
56
69
  The desktop app is the main workbench.
57
70
 
58
- The left side is the thread list. It groups the Template box, work on devboxes,
59
- and automations. New-thread controls let you choose an agent and whether to
60
- create a new devbox + thread or start a thread on the Template box.
71
+ The left side is the thread list. It groups work on devboxes, automations, and,
72
+ when the project has one, the Template box. New-thread controls let you choose
73
+ an agent and create a new devbox + thread. Projects with a Template box can
74
+ also start a thread there.
61
75
 
62
- The center pane shows the selected item: a thread transcript, the Template box
63
- page, or automation details. Thread transcripts are where you send follow-ups,
64
- watch agent progress, interrupt work, retry failed turns, and inspect the final
76
+ The center pane shows the selected item: a thread transcript, project page, or
77
+ automation details. Thread transcripts are where you send follow-ups, watch
78
+ agent progress, interrupt work, retry failed turns, and inspect the final
65
79
  response.
66
80
 
67
81
  The terminal pane connects to the selected runtime. If you select a devbox, the
@@ -79,9 +93,10 @@ staging, commits, branches, and history.
79
93
 
80
94
  ## Setup Thread Versus Your Threads
81
95
 
82
- The setup thread is created for initial project setup. It can also be useful for
83
- follow-up setup questions because it has the setup context, but you do not need
84
- to keep using it forever.
96
+ For a project with a Template box, the setup thread is created for initial
97
+ project setup. It can also be useful for follow-up setup questions because it
98
+ has the setup context, but you do not need to keep using it forever. Team
99
+ Template member projects do not have a personal setup thread.
85
100
 
86
101
  Template box threads can also be setup-oriented. They are often convenient for
87
102
  questions about the codebase or environment that do not require edits, and for
@@ -98,9 +113,12 @@ agent auth later from the desktop app. On macOS, open the boxes.dev app menu and
98
113
  choose **Configure agents...**.
99
114
 
100
115
  Codex can be connected with ChatGPT login or an API key. Claude Code can be
101
- connected with Claude login or an API key. If a thread cannot start because an
102
- agent is not authenticated, open Configure agents, reconnect the agent, and then
103
- start or retry the thread.
116
+ connected with Claude login or an API key. Configure agents can keep multiple
117
+ accounts or API keys for each agent; choose the active credential with its
118
+ radio control. That choice is global across your devboxes, and Codex and Claude
119
+ can use different active accounts. If a thread cannot start because an agent is
120
+ not authenticated, open Configure agents, reconnect or choose another saved
121
+ credential, and then start or retry the thread.
104
122
 
105
123
  ## First Useful Task
106
124
 
@@ -125,4 +143,4 @@ For deeper detail, use the feature docs:
125
143
  - Read `threads-and-agents.md` for thread controls.
126
144
  - Read `desktop-workbench.md` for app navigation.
127
145
  - Read `files-git-and-review.md` for code review and git.
128
- - Read `ports-terminal-and-runtime.md` for ports, terminal, wake, and sleep.
146
+ - Read `ports-terminal-and-runtime.md` for ports, terminal, wake, and sleep.
@@ -53,9 +53,10 @@ A thread whose agent is Codex.
53
53
 
54
54
  ## Devbox
55
55
 
56
- An isolated cloud Linux development machine created from a Template box
57
- snapshot. A devbox has its own filesystem, processes, services, ports, local
58
- state, terminal sessions, and agent threads.
56
+ An isolated cloud Linux development machine created from the project's current
57
+ reusable source: a Template-box snapshot or a Team Template saved version. A
58
+ devbox has its own filesystem, processes, services, ports, local state,
59
+ terminal sessions, and agent threads.
59
60
 
60
61
  ## Thread on a Devbox
61
62
 
@@ -69,8 +70,9 @@ available to open or copy from the desktop app.
69
70
 
70
71
  ## Template box
71
72
 
72
- The persistent base machine for a project. Use it for shared setup,
73
- maintenance, snapshots, and setup-oriented work.
73
+ The persistent base machine for an ordinary project. Use it for shared setup,
74
+ maintenance, snapshots, and setup-oriented work. Team Template member projects
75
+ do not have one.
74
76
 
75
77
  ## Mobile App
76
78
 
@@ -80,7 +82,9 @@ phone.
80
82
 
81
83
  ## Project
82
84
 
83
- One codebase in boxes.dev. Each project has one Template box.
85
+ One codebase in boxes.dev. Most projects have one Template box. A Team Template
86
+ member project instead uses the Team Template's current saved version for
87
+ future devboxes.
84
88
 
85
89
  ## Runtime
86
90
 
@@ -10,20 +10,24 @@ specific feature doc only when needed.
10
10
 
11
11
  ## Product Model
12
12
 
13
- boxes.dev gives each project a persistent Template box and lets users create
14
- devboxes from it for isolated agent work. A devbox is a full cloud Linux machine
15
- with its own filesystem, running services, and ports, and it can host agent
16
- threads. The desktop app is the primary workbench; mobile and the CLI are
17
- companion control surfaces.
13
+ An ordinary boxes.dev project has a persistent Template box and creates
14
+ devboxes from its snapshots for isolated agent work. A Team Template can also
15
+ enable **Member projects**, which have no personal Template box and create
16
+ future devboxes from the Team Template's current saved version instead. A
17
+ devbox is a full cloud Linux machine with its own filesystem, running services,
18
+ and ports, and it can host agent threads. The desktop app is the primary
19
+ workbench; mobile and the CLI are companion control surfaces.
18
20
 
19
21
  Use this terminology consistently:
20
22
 
21
- - Template box: the persistent base machine for one project.
22
- - Devbox: an isolated machine created from a Template box snapshot for a task,
23
- thread, automation run, or integration-triggered run.
23
+ - Template box: the persistent base machine for one ordinary project. A Member
24
+ project does not have one.
25
+ - Devbox: an isolated machine created from a project snapshot or a Team
26
+ Template's saved version for a task, thread, automation run, or an
27
+ integration-triggered run.
24
28
  - Thread: a Codex or Claude conversation connected to a runtime. In the
25
29
  desktop app, the same thread can use GUI or Terminal view.
26
- - Snapshot: the saved running state used to create future devboxes.
30
+ - Snapshot: a saved filesystem state used to create future devboxes.
27
31
  - Selected runtime: the Template box or devbox currently selected in the app;
28
32
  terminals, ports, files, and runtime controls follow that selection.
29
33
 
@@ -35,7 +39,7 @@ Use this terminology consistently:
35
39
  - `project-setup.md`: how project setup works, what the setup thread does, what
36
40
  gets uploaded, how setup can be retried, and when to use it again.
37
41
  - `team-template.md`: named team-wide starting environments, independent admin
38
- editing and releases, member project creation, Git personalization, and
42
+ editing and saved versions, member project creation, Git personalization, and
39
43
  copied-data boundaries.
40
44
  - `template-box-environment.md`: the Template box machine environment, baseline
41
45
  development tools, setup constraints, local-run verification, and snapshots.
@@ -80,9 +84,9 @@ Use this terminology consistently:
80
84
  role selection, the managed `boxes-dev` profile, credential precedence,
81
85
  refresh behavior, removal, and container limits.
82
86
  - `tailscale.md`: team-managed tailnet setup, Tailscale-policy-based project
83
- eligibility, tagged ephemeral Template boxes and devboxes, stock CLI
84
- behavior, snapshot identity rotation, native cleanup, incident removal, and
85
- version-one limits.
87
+ eligibility, tagged ephemeral project machines, stock CLI behavior, ordinary
88
+ snapshot identity rotation, native cleanup, incident removal, and version-one
89
+ limits.
86
90
  - `billing-and-limits.md`: plans, box-hours, awake runtimes, awake devbox
87
91
  limits, project limits, usage, overages, checkout, and billing portal
88
92
  behavior.
@@ -41,36 +41,38 @@ Open a project to see its threads. The list can include:
41
41
  - drafts that have not sent their first message yet.
42
42
 
43
43
  Opening the project, browsing its thread history, or editing an unstarted draft
44
- does not wake or connect to the Template box. Mobile connects only after you
45
- open a live thread that has a runtime, or choose an action such as Send,
46
- Terminal, Files, snapshot, sleep, or destroy that needs one. A live devbox
47
- thread connects to that exact devbox rather than the Template box.
48
-
49
- The new-thread button first asks whether to create a **New devbox + thread** or
50
- a **New thread on template**. After you choose, it opens one draft at that
51
- location. The draft uses the project's last Codex or Claude choice from mobile,
52
- desktop, or `dvb agents`, and otherwise uses Codex unless you configured only
53
- Claude during desktop setup. Codex and Claude are the agent choices, with no
54
- separate Claude CLI thread type for new work. A new devbox starts from the
55
- latest Template-box snapshot, whose date and time appear below the agent
56
- selector. Inside an existing devbox group, **New thread** opens a draft directly
57
- on that same devbox, where you choose the agent before sending.
44
+ does not wake or connect to a machine. Mobile connects only after you open a
45
+ live thread that has a runtime, or choose an action such as Send, Terminal,
46
+ Files, snapshot, sleep, or destroy that needs one. A live devbox thread connects
47
+ to that exact devbox rather than another project machine.
48
+
49
+ In an ordinary project, the new-thread button first asks whether to create a
50
+ **New devbox + thread** or a **New thread on template**. A Team Template member
51
+ project has no template choice and opens a new-devbox draft directly. The draft
52
+ uses the project's last Codex or Claude choice from mobile, desktop, or
53
+ `dvb agents`, and otherwise uses Codex unless you configured only Claude during
54
+ desktop setup. Codex and Claude are the agent choices, with no separate Claude
55
+ CLI thread type for new work. An ordinary new devbox starts from the latest
56
+ Template-box snapshot; a member-project devbox starts from the Team Template's
57
+ current saved version. Inside an existing devbox group, **New thread** opens a
58
+ draft directly on that same devbox, where you choose the agent before sending.
58
59
 
59
60
  Thread menus support common actions such as opening, renaming, pinning,
60
61
  unpinning, marking unread, archiving, unarchiving, deleting when available, and
61
62
  ending live sessions. Eligible Codex and Claude threads on the Template box can
62
63
  be moved to a new devbox after their current turn finishes.
63
64
 
64
- From an open Template-box thread, use **New snapshot** in the header overflow
65
+ For an ordinary project, from an open Template-box thread, use **New snapshot** in the header overflow
65
66
  menu to update the snapshot used by future devboxes. The Template box briefly
66
67
  becomes unavailable while the snapshot is created; the mobile app reports when
67
68
  it succeeds or why it could not start.
68
69
 
69
- An archived cold-storage thread stays readable on mobile without waking the
70
- Template box. Use **Restore thread**, then choose **To new devbox** to restore
71
- from the latest project snapshot or **To Template box** to use the existing
72
- Template-box path. Either choice returns the restored thread directly to the
73
- normal thread list.
70
+ An archived cold-storage thread stays readable on mobile without waking a
71
+ machine. In an ordinary project, use **Restore thread**, then choose **To new
72
+ devbox** to restore from the latest project snapshot or **To Template box** to
73
+ use the existing Template-box path. A Team Template member project offers only
74
+ **To new devbox** and pins the current Team Template saved version when the
75
+ restore starts. The restored thread returns directly to the normal thread list.
74
76
 
75
77
  For an eligible non-archived thread, **Mark unread** is available from both the
76
78
  thread-list menu and the open session's header menu. The thread stays unread
@@ -148,7 +150,7 @@ devbox pills. From a devbox row or devbox group you can:
148
150
  - destroy the devbox when you are finished.
149
151
 
150
152
  Destroying a devbox preserves the related threads as archived cold-storage
151
- transcripts. It does not copy them onto or wake the Template box. If the devbox
153
+ transcripts. It does not copy them onto or wake another machine. If the devbox
152
154
  has local changes or local-only commits, the confirmation text calls that out
153
155
  before you destroy it.
154
156
 
@@ -202,8 +204,9 @@ Mobile settings include:
202
204
  - release package details and refresh controls in installed builds;
203
205
  - account deletion.
204
206
 
205
- Account deletion permanently deletes your boxes.dev account and associated
206
- projects, Template boxes, and devboxes. It cannot be undone.
207
+ Account deletion permanently deletes your boxes.dev account, projects,
208
+ personal Template boxes, and devboxes. Team Templates belong to the team and
209
+ are not deleted with one member's account. The deletion cannot be undone.
207
210
 
208
211
  ## Mobile Versus Desktop
209
212
 
@@ -54,6 +54,12 @@ MCPs**. Codex-synced plugins use Codex's own trusted install flow. Local Codex
54
54
  plugins, Claude plugins, and unsupported/local MCPs belong on the Template box
55
55
  when they should become part of future devboxes.
56
56
 
57
+ A Team Template member project has no personal Template box. Native-only
58
+ Plugins and unsupported/local MCPs installed on one of its devboxes stay on
59
+ that exact devbox; the member cannot publish them into the shared Team
60
+ Template. Centrally managed project MCPs continue to use **Integrations →
61
+ MCPs** normally.
62
+
57
63
  Do not infer Codex plugin authority from a local cache path: Codex can cache a
58
64
  synced plugin on every host. A supported public GitHub plugin installed on a
59
65
  managed box is verified and becomes managed for this project automatically;
@@ -311,13 +317,14 @@ Codex model, reasoning, and Standard/Fast mode or Claude model and reasoning.
311
317
  If that source box has no saved defaults for the agent, the managed catalog
312
318
  default is used.
313
319
 
314
- The new devbox belongs to the source box's project and uses the latest eligible
315
- Template-box snapshot. If no eligible snapshot exists, the command fails with
316
- `snapshot_required`; it never snapshots or clones the live source box. Files,
317
- edits, branches, and commits that exist only on the source devbox are absent.
318
- Push a needed commit to a Git remote and tell the child to fetch and check it
319
- out, or use `current-devbox`; pushing alone does not change the commit checked
320
- out in the new devbox.
320
+ The new devbox belongs to the source box's project and uses that project's
321
+ current reusable source. An ordinary project uses its latest eligible
322
+ Template-box snapshot and returns `snapshot_required` when none exists. A Team
323
+ Template member project uses the current saved version. The command never
324
+ snapshots or clones the live source box. Files, edits, branches, and commits
325
+ that exist only on the source devbox are absent. Push a needed commit to a Git
326
+ remote and tell the child to fetch and check it out, or use `current-devbox`;
327
+ pushing alone does not change the commit checked out in the new devbox.
321
328
 
322
329
  To start another thread on an ordinary devbox, use its instance ID:
323
330
 
@@ -161,12 +161,13 @@ unavailable page for up to one minute while its availability refreshes; retry
161
161
  the link after that interval.
162
162
 
163
163
  Choose **Configure port forwarding…** for project-level rules. The same
164
- configuration applies to the project's Template box and every devbox, while
165
- ordinary localhost forwarding follows the selected machine. Stable local URLs
166
- remain active for every opted-in devbox. New projects forward detected ports
167
- to the matching local port by default. Configuration can change that default,
168
- allow or exclude individual ports and inclusive ranges, and map remote ports or
169
- ranges to different local ports.
164
+ configuration applies to every real machine in the project: the Template box
165
+ and devboxes in an ordinary project, or only assigned devboxes in a Team
166
+ Template member project. Ordinary localhost forwarding follows the selected
167
+ machine. Stable local URLs remain active for every opted-in devbox. New projects
168
+ forward detected ports to the matching local port by default. Configuration can
169
+ change that default, allow or exclude individual ports and inclusive ranges,
170
+ and map remote ports or ranges to different local ports.
170
171
 
171
172
  Rules are evaluated from top to bottom, and the first matching rule wins. The
172
173
  editor warns about overlaps and rules with no effect, and its expandable
@@ -212,9 +213,10 @@ The desktop app menu has **Machine > Reset** when the selected managed runtime
212
213
  is running. Reset kills shells, agent sessions, background commands, and user
213
214
  services, while preserving files and keeping the runtime running.
214
215
 
215
- If a devbox thread is selected, reset targets that devbox. Otherwise it targets
216
- the Template box. boxes.dev confirms before resetting and then reports what was
217
- stopped.
216
+ If a devbox thread is selected, reset targets that devbox. In an ordinary
217
+ project, selecting the Template box targets it instead. A project with no
218
+ selected real runtime has no reset target. boxes.dev confirms before resetting
219
+ and then reports what was stopped.
218
220
 
219
221
  ## Reboot (Last Resort)
220
222
 
@@ -5,9 +5,12 @@ why a setup step is waiting, how to resume setup, or how to add another project.
5
5
 
6
6
  ## What Setup Creates
7
7
 
8
- Project setup creates one project with one Template box. The Template box is
9
- the persistent base machine for that project. After setup, future Devboxes
10
- start from snapshots of this Template box.
8
+ The local-folder, agent-driven, and direct GitHub setup paths described here
9
+ create one ordinary project with one Template box. The Template box is the
10
+ persistent base machine for that project. After setup, future devboxes start
11
+ from snapshots of this Template box. A Team Template can separately enable
12
+ **Member projects**, which have no personal Template box; see
13
+ `team-template.md` for that flow.
11
14
 
12
15
  The recommended setup path is the desktop local-folder flow. It uploads local
13
16
  project state and starts a setup thread on the Template box. That thread applies
@@ -151,8 +154,10 @@ Setup asks the user to connect at least one coding agent:
151
154
 
152
155
  Users can connect both, but only one is required to start. If auth was skipped
153
156
  for one agent, or if auth later breaks, use Configure agents in the desktop app
154
- to connect, reconnect, edit an API key, re-auth, or disconnect an agent. On
155
- macOS, Configure agents is in the boxes.dev app menu.
157
+ to add another account or API key, choose the active credential, edit an API
158
+ key, re-auth, remove a saved credential, or disconnect an agent. The active
159
+ Codex and Claude choices are independent and apply globally across the user's
160
+ devboxes. On macOS, Configure agents is in the boxes.dev app menu.
156
161
 
157
162
  Configure agents manages the Codex and Claude accounts that run coding-agent
158
163
  threads. Remote MCP connections are managed separately from **Integrations →
@@ -170,11 +175,14 @@ GitHub turns on **GitHub CLI in devboxes**, and the checkbox is selected by
170
175
  default; clear it before continuing to turn the grant back off. The same
171
176
  account-wide choice remains manageable under **Integrations → GitHub → GitHub
172
177
  CLI in devboxes** and applies to all current and future Template boxes and
173
- devboxes. It does not change repository remotes or the project's Git pull/push
174
- access method.
175
- While it is enabled, users should not run `gh auth login` or `gh auth logout`.
176
- When it is disabled, or GitHub is not connected to boxes.dev, `gh` uses its
177
- ordinary user-managed configuration and environment.
178
+ devboxes. Effective managed access remains project-specific: boxes.dev issues
179
+ no managed token when its connected GitHub App credential cannot access every
180
+ known repository in the current project. It does not change repository remotes
181
+ or the project's Git pull/push access method.
182
+ While managed access is effective, users should not run `gh auth login` or `gh
183
+ auth logout`. When the choice is disabled, GitHub is not connected to boxes.dev,
184
+ or project repository access is missing, `gh` uses its ordinary machine-local
185
+ configuration and environment.
178
186
 
179
187
  boxes.dev stores centrally managed remote MCP definitions and credentials,
180
188
  refreshes OAuth when the provider supports it, and applies the current version
@@ -269,8 +277,9 @@ installation so the new repository can be granted access before checking again.
269
277
  Canceling setup or deleting the boxes.dev project does not delete a repository
270
278
  created on GitHub.
271
279
 
272
- A GitHub-created project can contain up to 20 selected repositories, but it
273
- still creates exactly one project and one Template box. Setup starts in
280
+ A project created through this direct GitHub path can contain up to 20 selected
281
+ repositories, but it still creates exactly one ordinary project and one
282
+ Template box. Setup starts in
274
283
  single-repository mode; switching it to multiple repositories is an explicit
275
284
  choice to combine several repositories into one project. With one repository,
276
285
  the repository is the project root. With several repositories, the project root
@@ -669,8 +678,11 @@ To upload another local project, use **New project...** in the titlebar project
669
678
  selector or **File > New Project...** in the desktop app. On the website,
670
679
  **New project** opens the same three setup paths offered before the first
671
680
  project exists. For a repository that is not on the user's computer, **Create
672
- from GitHub** clones another GitHub-backed project instead, with the same manual
673
- environment setup afterwards. Each project has one Template box, so another
674
- project gets its own setup flow and its own Template box. Existing agent auth
675
- can be reused by local-folder setup, but each local project still needs its own
676
- folder selection, scans, review, upload, remote setup, and first snapshot.
681
+ from GitHub** clones another GitHub-backed ordinary project instead, with the
682
+ same manual environment setup afterwards. Each ordinary project made through
683
+ these paths gets its own setup flow and Template box. A Team Template's
684
+ **Member projects** path is the exception: it creates an independent project
685
+ without a personal Template box and uses the Team Template's current saved
686
+ version for future devboxes. Existing agent auth can be reused by local-folder
687
+ setup, but each local project still needs its own folder selection, scans,
688
+ review, upload, remote setup, and first snapshot.
@@ -148,19 +148,24 @@ revoke a token already returned to a process. GitHub attributes the Git
148
148
  operation to the connected user.
149
149
 
150
150
  Connecting or reconnecting GitHub enables **GitHub CLI in devboxes** by default
151
- under **Integrations → GitHub**. This account-wide grant lets `gh`, coding
152
- agents, aliases, extensions, and other same-user code use the connected identity
153
- on every current and future Template box and devbox. boxes.dev does not write
154
- the credential to native `gh` configuration or a managed credential file, but
155
- it can exist in the local service, `gh`, child-process, Git, and snapshot
156
- process memory. Because the user fully owns these machines, avoiding a token
157
- file reduces accidental persistence and disclosure; it is not a boundary
158
- against the user or code they run. Disabling the setting stops new managed CLI
159
- requests on connected machines and clears the managed CLI's local cache. The
160
- CLI then uses ordinary user-managed configuration and environment credentials
161
- when present. Disabling does not revoke copies already held by running
162
- processes or an offline machine, rotate the shared GitHub credential, or
163
- interrupt the separate automatic Git pull/push helper.
151
+ under **Integrations → GitHub**. This account-wide preference lets `gh`, coding
152
+ agents, aliases, extensions, and other same-user code request the connected
153
+ identity on current and future Template boxes and devboxes. Before issuing it,
154
+ boxes.dev confirms that the token can access every known GitHub repository in
155
+ the current project. A failed exact repository check returns no managed token
156
+ and leaves `gh` in ordinary machine-local mode for that project.
157
+
158
+ boxes.dev does not write the managed credential to native `gh` configuration
159
+ or a managed credential file, but it can exist in the local service, `gh`,
160
+ child-process, Git, and snapshot process memory. Because the user fully owns
161
+ these machines, avoiding a token file reduces accidental persistence and
162
+ disclosure; it is not a boundary against the user or code they run. Disabling
163
+ the setting stops new managed CLI requests on connected machines and clears the
164
+ managed CLI's local cache. The CLI then uses ordinary user-managed
165
+ configuration and environment credentials when present. Disabling does not
166
+ revoke copies already held by running processes or an offline machine, rotate
167
+ the shared GitHub credential, or interrupt the separate automatic Git pull/push
168
+ helper.
164
169
 
165
170
  The AWS integration stores the user's renewable IAM Identity Center sign-in
166
171
  encrypted in boxes.dev. That renewable sign-in is not copied onto Template
@@ -195,14 +200,23 @@ Template boxes and devboxes are full cloud Linux development machines. Agents
195
200
  and users can run commands, edit files, install dependencies, open ports, and
196
201
  interact with local services inside either machine.
197
202
 
203
+ A Team Template member project has no personal Template box. Team admins author
204
+ its shared saved files in separate Team Template editing machines, and members
205
+ cannot access those machines through their projects. A prepared member devbox
206
+ runs the team-authored startup script before boxes.dev installs that member's
207
+ agent, GitHub, AWS, Tailscale, MCP, and other personal state. Once assigned, the
208
+ devbox belongs only to that member and is never returned to another member's
209
+ prepared pool.
210
+
198
211
  Anything available inside the selected machine can usually be read or changed by
199
212
  the agent running there. This includes checked-out code, local env files, local
200
213
  databases, generated files, and credentials copied into the environment.
201
214
 
202
- Devboxes are isolated from the Template box after they are created. A devbox has
215
+ Devboxes are isolated from their source after they are created. A devbox has
203
216
  its own filesystem, processes, ports, local database state, and agent threads.
204
- Work done on a devbox does not automatically change the Template box unless the
205
- user copies, commits, pushes, merges, or otherwise moves the changes.
217
+ Work done on a devbox does not automatically change an ordinary project's
218
+ Template box or a Team Template saved version. Move changes intentionally with
219
+ Git or another explicit workflow.
206
220
 
207
221
  ## Files, Transcripts, And Metadata
208
222
 
@@ -260,9 +274,11 @@ the legal privacy policy at `https://boxes.dev/privacy`.
260
274
 
261
275
  ## Deleting Projects And Devboxes
262
276
 
263
- Deleting a project permanently deletes its Template box, its descendant
264
- devboxes, snapshots, and all associated data. The product asks the user to type
265
- the project name before deletion. Treat project deletion as irreversible.
277
+ Deleting a project permanently deletes its personal Template box when it has
278
+ one, its devboxes, snapshots, threads, and attached project data. Deleting a
279
+ Team Template member project does not delete the shared Team Template or affect
280
+ another member's project. The product asks the user to type the project name
281
+ before deletion. Treat project deletion as irreversible.
266
282
 
267
283
  Destroying an individual devbox permanently deletes that devbox's filesystem and
268
284
  archives its threads. Save any useful work before confirming destruction.
@@ -285,6 +301,9 @@ Account deletion deletes:
285
301
  ports, active session metadata, and short session title summaries.
286
302
  - Remote machines, snapshots, and their stored data.
287
303
 
304
+ Team-owned Team Templates and other members' projects remain with the team when
305
+ one member deletes their account.
306
+
288
307
  Account deletion is permanent and cannot be undone.
289
308
 
290
309
  If a user cannot access their account, they can email hi@boxes.dev from the
@@ -1,7 +1,9 @@
1
1
  # Tailscale Integration
2
2
 
3
- The Tailscale integration connects a project's Template box and devboxes to a
4
- team's tailnet as tagged, ephemeral Tailscale devices. A team admin connects the
3
+ The Tailscale integration connects a project's machines to a team's tailnet as
4
+ tagged, ephemeral Tailscale devices. For an ordinary project, that includes its
5
+ Template box and devboxes. A Team Template member project has no personal
6
+ Template box, so only its assigned devboxes connect. A team admin connects the
5
7
  tailnet once, and each project owner verifies their own access before enabling
6
8
  the integration for that project. No one signs in to Tailscale separately on
7
9
  each project machine.
@@ -82,7 +84,7 @@ or group to the boxes.dev tag.
82
84
 
83
85
  Access to the tag controls who can enable Tailscale for a project. Once it is
84
86
  enabled, the tag's network access is available to anyone or any automation that
85
- can run commands on that project's Template box or devboxes. Admins should
87
+ can run commands on that project's machines. Admins should
86
88
  separately control who can use the project, its machines, and its automations.
87
89
 
88
90
  Rules whose source is the boxes.dev tag control what connected project machines
@@ -92,7 +94,7 @@ controls who may enable the integration.
92
94
  ## Project Machine Experience
93
95
 
94
96
  After the project owner enables Tailscale, boxes.dev installs the pinned
95
- official Tailscale client on the Template box and devboxes and enrolls them
97
+ official Tailscale client on the project's real machines and enrolls them
96
98
  automatically when they want to run. The ordinary `tailscale` CLI is available
97
99
  on the standard socket. Users and scripts can use stock commands such as
98
100
  `tailscale status`, `tailscale ping`, `tailscale down`, `tailscale up`, and
@@ -126,13 +128,15 @@ long sleep and replaces that identity if Tailscale's ephemeral cleanup removed
126
128
  it. Short sleeps normally reuse the same identity. If the machine or Tailscale
127
129
  cannot be checked safely, boxes.dev retains the device lease and retries later.
128
130
 
129
- A Template snapshot briefly disconnects the Template box from Tailscale.
130
- boxes.dev removes its current device identity before capturing the snapshot,
131
- proves the saved image contains no Tailscale identity, and then enrolls the live
132
- Template box again. Its MagicDNS hostname stays the same, but its device ID,
133
- node key, and Tailscale IP can change. Use the MagicDNS hostname rather than a
134
- numeric Tailscale IP for applications running on the Template box. Devboxes
135
- created from the snapshot enroll with their own distinct identities.
131
+ A snapshot used to create a devbox briefly disconnects only the exact source
132
+ box from Tailscale. The source can be the project's Template box or an ordinary
133
+ devbox selected by **Continue in new chat → New devbox**. boxes.dev removes that
134
+ source's current device identity before capture, proves the saved image contains
135
+ no Tailscale identity, and then enrolls the live source again. Other devboxes in
136
+ the project stay connected. The source's MagicDNS hostname stays the same, but
137
+ its device ID, node key, and Tailscale IP can change. Use the MagicDNS hostname
138
+ rather than a numeric Tailscale IP for applications running there. The new
139
+ devbox enrolls with its own distinct identity.
136
140
 
137
141
  Disabling Tailscale for a project deletes its recorded Tailscale devices and
138
142
  purges their local identities without waking sleeping machines. Destroying a