@boxes-dev/dvb-runtime 1.0.1012 → 1.0.1015

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.
Files changed (31) hide show
  1. package/dist/agent-init-guides/env-files.md +29 -3
  2. package/dist/agent-init-guides/flow.md +14 -1
  3. package/dist/agent-init-guides/manifest.md +4 -0
  4. package/dist/bin/dvb.mjs +2046 -1961
  5. package/dist/bin/dvbd.mjs +8 -8
  6. package/dist/product-docs/SKILL.md +4 -0
  7. package/dist/product-docs/references/agent-tools.md +3 -3
  8. package/dist/product-docs/references/automations.md +10 -6
  9. package/dist/product-docs/references/aws.md +4 -3
  10. package/dist/product-docs/references/billing-and-limits.md +6 -4
  11. package/dist/product-docs/references/core-concepts.md +3 -3
  12. package/dist/product-docs/references/desktop-workbench.md +17 -4
  13. package/dist/product-docs/references/environment-setup-validation.md +44 -0
  14. package/dist/product-docs/references/files-git-and-review.md +46 -11
  15. package/dist/product-docs/references/fork-workflows.md +21 -9
  16. package/dist/product-docs/references/glossary.md +5 -2
  17. package/dist/product-docs/references/index.md +9 -3
  18. package/dist/product-docs/references/linear.md +10 -7
  19. package/dist/product-docs/references/member-managed-files.md +5 -2
  20. package/dist/product-docs/references/mobile.md +9 -4
  21. package/dist/product-docs/references/onbox-agent-tools.md +102 -40
  22. package/dist/product-docs/references/ports-terminal-and-runtime.md +24 -9
  23. package/dist/product-docs/references/project-setup.md +8 -0
  24. package/dist/product-docs/references/security-and-data.md +43 -26
  25. package/dist/product-docs/references/slack.md +45 -15
  26. package/dist/product-docs/references/tailscale.md +3 -0
  27. package/dist/product-docs/references/team-template.md +30 -41
  28. package/dist/product-docs/references/template-box-environment.md +5 -0
  29. package/dist/product-docs/references/threads-and-agents.md +38 -15
  30. package/dist/product-docs/references/troubleshooting.md +35 -26
  31. package/package.json +2 -2
@@ -29,9 +29,11 @@ and permission-request commands still enforce the source box, thread, owner,
29
29
  and current setting.
30
30
 
31
31
  The Team Template commands are the exception to the settings model. Their
32
- skill can be present on a project Template box even when it has no Team
33
- Template access. The exact active editing association described below is the
34
- authority, and an unassociated box receives no targets.
32
+ skill is available in Team Template editing sessions and can also be present
33
+ on a project Template box without Team Template access. Direct editing uses
34
+ the current editing session; remote work from an ordinary Template box needs
35
+ the exact active association described below. An unassociated source box
36
+ receives no remote targets.
35
37
 
36
38
  ## Current Box Role
37
39
 
@@ -95,7 +97,7 @@ cleanup, final snapshot, and closeout request before that finalization finishes;
95
97
  after it accepts the request, send the final user-facing response. Do not use it
96
98
  to dismiss setup early or skip unfinished work.
97
99
 
98
- After the project runs successfully on the Template box, an agent can create the
100
+ After the app runs successfully on the Template box, an agent can create the
99
101
  snapshot used by future devboxes:
100
102
 
101
103
  ```bash
@@ -164,12 +166,13 @@ session. They update that Team Template's shared maintenance script and watches
164
166
  and require the editing session's owner to remain a team admin. Use repository
165
167
  paths from the Team Template's configured GitHub repositories. The JSON result
166
168
  identifies the Team Template by name and ID. Schedule settings remain editable
167
- in **Project defaults → Maintenance** in the desktop app.
169
+ under **Template environment → Maintenance** in the desktop app.
168
170
 
169
171
  These settings are devbox lifecycle and Template maintenance, not boxes.dev
170
172
  Automations. The commands accept no project, box, owner, or repository ID.
171
173
  Devbox lifecycle commands require the current ordinary Template box; configure
172
- Team Template lifecycle defaults in **Project defaults → Devbox lifecycle**.
174
+ Team Template lifecycle defaults under **When a new devbox is created**,
175
+ including its **When a devbox is destroyed** section.
173
176
  If either operation reports
174
177
  disabled access, request only `edit-devbox-lifecycle` or
175
178
  `edit-template-maintenance`, respectively.
@@ -220,9 +223,26 @@ stable structured result.
220
223
 
221
224
  The command creates one request for the exact managed thread and source box,
222
225
  then waits up to ten minutes while the owner sees **Allow** and **Not now** in
223
- boxes.dev. **Allow** changes the existing persistent Agent permission for every
224
- agent on that source box until the owner turns it off; it is not a one-operation
225
- grant. The command cannot answer its own request or affect another box.
226
+ boxes.dev. By default, **Allow** changes the existing persistent Agent permission
227
+ for every agent on that source box until the owner turns it off; it is not a
228
+ one-operation grant. The owner chooses the scope; an agent cannot answer its own
229
+ request.
230
+
231
+ For folder access, thread titles, and creating devboxes and threads, the owner
232
+ can choose **All my devboxes in this project** before selecting **Allow**.
233
+ This will enable the project's shared permission and make the requesting box
234
+ use it. All existing and future devboxes without an individual override will
235
+ inherit that setting. Other devboxes will keep their explicit allow or deny
236
+ overrides. The choice is personal to the owner's
237
+ project, including projects created from a Team Template; it will not change
238
+ teammates' permissions. Template-only permissions keep their existing scope.
239
+
240
+ Change a box's override through its **Agent permissions** control, or choose
241
+ **Use project setting** to restore inheritance. Change shared access under
242
+ **Agent permissions for this project** in Project settings. Turning off a project
243
+ permission revokes it for every box that inherits it; explicit box overrides
244
+ remain in effect. Grants saved before project inheritance remain individual
245
+ overrides until you choose **Use project setting**.
226
246
 
227
247
  Run the request once and wait. `granted` and `already_granted` are successful;
228
248
  `denied`, `expired`, and `permission_request_pending` are non-successful
@@ -250,10 +270,10 @@ Users can independently enable **Update thread titles** from the **Agent
250
270
  permissions** control in an owned Codex or Claude thread header. That header
251
271
  control is where a box's live permissions are edited, for the Template box and
252
272
  devboxes alike. The permission applies to agents on that exact box and does
253
- not enable delegated devbox or thread creation. A new devbox starts with the
254
- project's default for this permission, set under **Agent permissions for new
255
- devboxes** in Project settings; the default is off unless the
256
- project owner changes it, and changing it does not affect existing devboxes.
273
+ not enable delegated devbox or thread creation. Boxes without an override use
274
+ the shared permission under **Agent permissions for this project** in Project
275
+ settings. It is off unless the owner changes it; changes affect existing and
276
+ future boxes that use the project setting.
257
277
 
258
278
  When enabled, the agent can replace the current thread's manual title override:
259
279
 
@@ -307,13 +327,11 @@ A user can allow agents on one exact Template box or devbox to create delegated
307
327
  threads. The setting is off by default and applies to every agent on that source
308
328
  box. Users change **Create devboxes and threads** from the **Agent permissions**
309
329
  control in the thread header, which appears on any thread running on that box.
310
- Under **Agent permissions for new devboxes** in a project's Project settings,
311
- users can opt in to having every new devbox they or an agent creates in that
312
- project start with the permission enabled. The project default is off, is
313
- stamped only when the devbox is created, and never changes an existing box. A
314
- new thread on the same box uses that box's current live permission. A new
315
- devbox uses the project default rather than copying the source box's live
316
- permission.
330
+ Under **Agent permissions for this project** in Project settings, users can
331
+ enable the permission for all their existing and future devboxes without an
332
+ override. The shared setting is off by default. A new thread on the same box
333
+ uses that box's effective permission. A new devbox inherits the project's live
334
+ setting, and later project changes apply until the user sets a box override.
317
335
 
318
336
  The start request is the authoritative check. When delegation is off, it fails
319
337
  with `delegation_disabled` without creating a thread or devbox and names the
@@ -562,12 +580,12 @@ for each source box under **Agent permissions**:
562
580
  - **Move to folders and create folders** includes move access and permits
563
581
  creation.
564
582
 
565
- A new devbox starts at the project's folder-access default, set under **Agent
566
- permissions for new devboxes** in Project settings; that default is
567
- **No folder access** unless the project owner changes it, and changing it does
568
- not affect existing boxes. Folder access belongs to the source box, not a
569
- thread: a new thread on the same box uses that box's current folder access, but
570
- the source box's permission does not transfer to a newly created devbox. The
583
+ A devbox without an override inherits the project's live folder access under
584
+ **Agent permissions for this project** in Project settings. The shared setting
585
+ is **No folder access** unless the owner changes it; changes apply to existing
586
+ and future inheriting boxes. Folder access belongs to the source box, not a
587
+ thread: a new thread on the same box uses that box's effective folder access,
588
+ while a new devbox inherits the project setting. The
571
589
  current source box determines the project; there is no project flag or project
572
590
  inventory command.
573
591
 
@@ -721,6 +739,51 @@ the file is missing, run the ordinary OAuth flow unchanged.
721
739
 
722
740
  ## Team Template Commands
723
741
 
742
+ ### Choose the execution mode
743
+
744
+ Run `dvb-onbox box status --json` before choosing a workflow:
745
+
746
+ - `team_template_edit_box`: the agent runs directly on the Team Template
747
+ editing machine. Use **Work directly on a Team Template editing box** below.
748
+ - `template_box`: local shell commands affect an ordinary project's Template
749
+ box. To edit an associated Team Template, use **Work on a Team Template from
750
+ an ordinary Template box**. To create a new definition from the current
751
+ project, use **Create a Team Template from this project**.
752
+ - `devbox`: local edits affect only this devbox. These creation and remote
753
+ editing commands require an ordinary Template box; do not treat this devbox
754
+ as the shared template.
755
+
756
+ Skill availability is not proof of an editing association. If role inspection
757
+ fails, report the command's error and use only the operations whose target is
758
+ established; do not interpret an unavailable role as proof that the user needs
759
+ to reconnect. Preparing an existing template does not require creating another
760
+ definition.
761
+
762
+ For environment setup or repair in either editing mode, read
763
+ [Development environment validation](environment-setup-validation.md).
764
+
765
+ ### Work directly on a Team Template editing box
766
+
767
+ Codex and Claude threads opened directly in the Team Template editor execute
768
+ on its current editing machine. Ordinary file and shell tools operate on that
769
+ checkout. Use the actual repository paths there; do not use remote `exec` or
770
+ `push` commands to reach the machine you already occupy.
771
+
772
+ This editing machine is not an ordinary project's Template box. Use
773
+ `dvb-onbox project maintenance get|apply` for its Team Template maintenance
774
+ policy and the **Member-file requirements** commands for member-file
775
+ definitions. Ordinary project setup completion, project lifecycle commands,
776
+ and `dvb-onbox snapshot` are not the Team Template save workflow. Configure
777
+ startup behavior in the Team Template's **When a new devbox is created** card
778
+ and use the editor's save flow when the user has requested publication. See
779
+ [Team Templates](team-template.md) for the editing lifecycle and project modes.
780
+
781
+ Saving this checkout cleans and cold-boots the editing machine before capturing
782
+ the saved version. This differs from **Create a Team Template from this
783
+ project**, which starts with clean clones and does not copy the source
784
+ project's home directory. Keep personal credentials out of the shared authored
785
+ environment; do not assume arbitrary home files are excluded.
786
+
724
787
  ### Member-file requirements
725
788
 
726
789
  An admin can list, add, update, and remove the files members need to provide for
@@ -941,14 +1004,14 @@ release pipeline. Requested member project creation becomes active only after
941
1004
  the first saved release is eligible. `edit-box discard` is only for the
942
1005
  unsaved draft created through this path.
943
1006
 
944
- ### Work on an existing Team Template checkout
1007
+ ### Work on a Team Template from an ordinary Template box
945
1008
 
946
- While editing a Team Template, a team admin can open the editor's **Agent**
947
- pane, choose Codex or Claude, and select one of their project Template boxes.
948
- boxes.dev creates an ordinary thread on that selected Template box and gives
949
- the box access to this exact Team Template editing session. Agents and other
950
- processes on the selected box can use that access; it is source-box access, not
951
- a permission limited to the one visible chat.
1009
+ This section applies to an agent on an ordinary project's Template box with an
1010
+ active association to a Team Template editing session, including one created
1011
+ through the creation workflow above. It does not describe a thread running
1012
+ directly in the Team Template editor. Agents and other processes on the
1013
+ associated source box can use that access; it is source-box access, not a
1014
+ permission limited to one visible chat.
952
1015
 
953
1016
  The agent still runs on the project Template box. Ordinary shell commands read
954
1017
  and change that project's files. Team Template work goes through the commands
@@ -966,13 +1029,12 @@ dvb-onbox team-template push \
966
1029
  --destination /home/boxes/file-in-team-template
967
1030
  ```
968
1031
 
969
- There is no persistent toggle for access to an existing edit checkout. Access begins when the admin starts the
970
- Agent-pane chat and remains attached to that editing session across pane
971
- switches, desktop reloads, and app closure. It ends when the admin chooses
972
- **Stop agent**, saves, discards, loses the editing session, or another
973
- lifecycle event closes the checkout. The ordinary Codex or Claude thread stays
974
- in the source project afterward, but it cannot list or reach the ended editing
975
- session. Starting a later editing session requires a new Agent-pane association.
1032
+ There is no persistent toggle for access to an existing edit checkout. The
1033
+ association belongs to that editing session and can survive desktop reloads
1034
+ and app closure. Access ends when the association is stopped, the checkout is
1035
+ saved or discarded, or its editing authority is lost. The ordinary Codex or
1036
+ Claude thread stays in the source project afterward, but cannot list or reach
1037
+ the ended editing session. A later checkout needs its own active association.
976
1038
 
977
1039
  `exec` is noninteractive, receives no stdin, and is limited to 120 seconds and
978
1040
  1 MiB for each output stream. Optional `--timeout-seconds`,
@@ -14,8 +14,10 @@ the awake devbox limit.
14
14
 
15
15
  When the runtime is running, open the status menu to sleep it. The same menu can
16
16
  also toggle whether sleeping Template boxes and devboxes wake automatically when
17
- you return to them. When auto-wake is off, passive navigation leaves the runtime
18
- asleep until you explicitly wake it.
17
+ you return to them. Auto-wake is on by default and is saved as an account
18
+ preference. When auto-wake is off, passive navigation leaves the runtime
19
+ asleep. Explicitly sending a message to a Codex or Claude thread will still
20
+ wake its machine through the normal wake flow, even with auto-wake off.
19
21
 
20
22
  When the runtime is sleeping, use Wake from the status pill, Terminal, Files,
21
23
  Git, or Ports. If a devbox is sleeping because the awake devbox limit is full,
@@ -47,6 +49,9 @@ Common terminal actions:
47
49
  - If a detached session is shown, choose Connect to attach to it again.
48
50
  - If the selected runtime is sleeping, use Wake before terminal sessions load.
49
51
 
52
+ Closing a terminal tab ends that terminal session. Closing the desktop app
53
+ preserves open terminal sessions and restores their tabs when you reopen it.
54
+
50
55
  **Desktop app settings > Connection** includes a Terminal Connection choice.
51
56
  Managed is the default attachment transport. Direct (Mosh) negotiates an
52
57
  encrypted UDP path for the lowest latency and repairs that path if connectivity
@@ -133,9 +138,14 @@ globe action to create an HTTPS public link for that exact port. Anyone with
133
138
  the link can use the application without signing in. After you confirm, the
134
139
  dialog shows the new link with a **Copy link** button. Public links do not
135
140
  depend on local forwarding, remain active when you select another devbox or
136
- close the desktop app, and stay in place until you stop sharing them. They do
137
- not wake a sleeping devbox: while the devbox sleeps, visitors see an
138
- unavailable page and the Ports menu marks the link as paused.
141
+ close the desktop app, and remain allocated while the app is stopped or the
142
+ machine is sleeping. Traffic through a public link can keep an awake machine
143
+ active; Project URL traffic does not. Public links do not wake a sleeping
144
+ devbox: while the devbox sleeps, visitors see an unavailable page and the
145
+ Ports menu marks the link as paused.
146
+
147
+ If recovery replaces the machine, boxes.dev will revoke its old public links.
148
+ Share the app again on the recovered machine to get a new URL.
139
149
 
140
150
  The Ports button and menu cover only the selected Template box or devbox. The
141
151
  button shows that machine's active-link count, each detected port row offers
@@ -209,13 +219,18 @@ unavailable.
209
219
  ## Runtime Usage And Activity
210
220
 
211
221
  When live metrics are available, the titlebar can show CPU and memory usage.
212
- Memory usage excludes file cache when boxes.dev can identify it. Hover for more
213
- detail about CPU, memory, disk, and when the sample was updated.
222
+ Memory usage covers the whole machine, including containers and system services,
223
+ and accounts for memory the system can reclaim. Hover to see available memory,
224
+ CPU and disk details, and when the sample was updated. While a devbox is waiting
225
+ for a service update, its tooltip may show **Workload memory** instead, which
226
+ covers only the processes managed by boxes.dev.
214
227
 
215
228
  Click the usage indicator to open Activity. Activity lists processes inside the
216
229
  selected runtime, with command, CPU, memory, PID, and owner labels when
217
- available. Activity rows show per-process memory, so row totals may differ from
218
- the titlebar summary. You can sort by CPU or memory.
230
+ available. Activity's **Workload memory** total covers that workload, while the
231
+ titlebar shows the whole machine. Per-process memory figures may also include
232
+ shared memory, so the rows do not necessarily add up to either total. You can
233
+ sort by CPU or memory.
219
234
 
220
235
  Activity can terminate a process. If it keeps running after terminate, the UI
221
236
  can offer Force kill. Use these actions only when you understand what the
@@ -57,6 +57,14 @@ During Finalize Bundle, Agent threads lets users choose Codex or Claude history
57
57
  to import. The picker defaults to threads from the selected project repos and
58
58
  their Git worktrees, with a show-all option for other local history.
59
59
 
60
+ You can set up a linked Git worktree. Desktop setup will remind you that local
61
+ config such as `.env` files may be missing; choose the checkout where your app
62
+ runs, or continue with the worktree if it has the configuration you need.
63
+ Agent-driven setup can inspect relevant missing configuration and, with your
64
+ approval, select individual files from the main checkout through the manifest's
65
+ `from:` option. It will copy those files to the Template box without changing
66
+ either local checkout. Other checkouts are not included automatically.
67
+
60
68
  If a local repository is shallow, **Finalize Bundle → Repository** will note
61
69
  that older commits won't be included. You can continue with the existing history.
62
70
  To include older commits, open **Get full history**, run `git fetch --unshallow`
@@ -123,37 +123,54 @@ Existing boxes.dev threads remain.
123
123
  Disconnecting GitHub removes the stored GitHub user tokens from boxes.dev and
124
124
  stops pull-request actions until the user reconnects. Repository access granted
125
125
  to the GitHub App is managed separately through **Manage repos**.
126
-
127
- For a GitHub-created project using automatic access, the connected user's
128
- GitHub App user token remains encrypted at rest in boxes.dev. When Git needs
129
- access, the machine requests that credential through a local helper. boxes.dev
130
- first checks that the exact repository was selected during project creation
131
- and that the connected user still has write access. The token can exist in the
132
- boxes.dev service, local service, Git process, and snapshot process memory, but
133
- is not written to the remote URL or a managed credential file.
134
-
135
- Repository selection is an issuance boundary, not a downscope on the token
136
- itself. Code running on the box can request and inspect the credential, whose
137
- access is the intersection of the connected user's repositories and the
138
- repositories and permissions granted to the boxes.dev GitHub App. Current
126
+ Disconnecting the main GitHub connection also removes optional personal access
127
+ and schedules that authorization for revocation with GitHub. **Disconnect
128
+ personal access** performs the personal-access removal and revocation without
129
+ disconnecting the main GitHub connection.
130
+
131
+ When automatic Git access uses the GitHub App, the connected user's App
132
+ credential remains encrypted at rest in boxes.dev. When Git needs access, the
133
+ machine requests that credential through a local helper. boxes.dev first checks
134
+ that the exact repository is associated with the project and that the connected
135
+ user still has write access. The token can exist in the boxes.dev service, local
136
+ service, Git process, and snapshot process memory, but is not written to the
137
+ remote URL or a managed credential file.
138
+
139
+ Repository selection is an issuance boundary, not a downscope on the App token
140
+ itself. Code running on the box can request and inspect the App credential,
141
+ whose access is the intersection of the connected user's repositories and the
142
+ repositories and permissions granted to the boxes.dev GitHub App. Current App
139
143
  connections use GitHub access tokens that last eight hours. boxes.dev refreshes
140
144
  them centrally with GitHub's rotating refresh credential, which remains
141
145
  encrypted in boxes.dev and is not copied to Template boxes or devboxes. A user
142
146
  who connected before this change may see a one-time connection update; their
143
147
  existing access keeps working until they complete it. After that update,
144
148
  boxes.dev waits for outstanding machine cache leases to drain before retiring
145
- the replaced long-lived token. Disconnecting GitHub or removing access stops
146
- future helper issuance after its bounded cache lease, but does not itself
147
- revoke a token already returned to a process. GitHub attributes the Git
148
- operation to the connected user.
149
+ the replaced long-lived token. Disconnecting the main GitHub connection or
150
+ removing App access stops future App helper issuance after its bounded cache
151
+ lease, but does not itself revoke an App token already returned to a process.
152
+ GitHub attributes the Git operation to the connected user.
153
+
154
+ Optional personal access uses the official GitHub CLI authorization the user
155
+ approved. Before boxes.dev issues this credential, the personal authorization
156
+ must match the main GitHub identity and pass the exact repository checks for the
157
+ operation. Those checks do not narrow the credential itself: code running on
158
+ the machine can inspect the full token, whose permissions come from the GitHub
159
+ CLI authorization rather than the GitHub App grants. Personal tokens can be
160
+ expiring or non-expiring. **Disconnect personal access** removes the saved
161
+ authorization and schedules its revocation with GitHub; a copy can remain
162
+ usable until GitHub completes the revocation.
149
163
 
150
164
  Connecting or reconnecting GitHub enables **GitHub CLI in devboxes** by default
151
165
  under **Integrations → GitHub**. This account-wide preference lets `gh`, coding
152
166
  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.
167
+ identity on current and future Template boxes and devboxes. Before issuing a
168
+ managed credential, boxes.dev checks that one authorization can access every
169
+ known GitHub repository in the current project. It prefers App access and can
170
+ use the user's separately authorized personal access when the App does not
171
+ provide the required repository access. If neither authorization passes those
172
+ checks, boxes.dev returns no managed token and leaves `gh` in ordinary
173
+ machine-local mode for that project.
157
174
 
158
175
  boxes.dev does not write the managed credential to native `gh` configuration
159
176
  or a managed credential file, but it can exist in the local service, `gh`,
@@ -202,11 +219,11 @@ interact with local services inside either machine.
202
219
 
203
220
  A Team Template member project has no personal Template box. Team admins author
204
221
  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.
222
+ cannot access those machines through their projects. Prepared devboxes belong
223
+ to one member and project. The team-authored startup script runs immediately
224
+ before the member's startup script, with the same prepared member credentials
225
+ and files available to both. Team admins are trusted authors of that code.
226
+ Once assigned to a draft, the devbox never returns to a prepared pool.
210
227
 
211
228
  Anything available inside the selected machine can usually be read or changed by
212
229
  the agent running there. This includes checked-out code, local env files, local
@@ -11,7 +11,8 @@ parts.
11
11
 
12
12
  You need:
13
13
 
14
- - a boxes.dev team with a Template box;
14
+ - a boxes.dev project with a usable Template box snapshot or saved Team Template
15
+ version;
15
16
  - team admin access in boxes.dev to connect the Slack workspace;
16
17
  - your own Slack identity linked to your boxes.dev user;
17
18
  - permission in Slack to install apps, or a Slack admin who can approve the
@@ -130,26 +131,54 @@ To start a thread in a teammate's workspace:
130
131
  The teammate mention must immediately follow `@boxes.dev`, and a request must
131
132
  follow the teammate mention. The teammate must have allowed you through their
132
133
  default Slack receiver's access setting. The new agent thread belongs to that
133
- teammate and uses their automation, Template box, devbox, credentials, and
134
+ teammate and uses their automation, saved project environment, devbox, credentials, and
134
135
  usage. It does not copy either teammate's existing devbox filesystem.
135
136
 
136
137
  boxes.dev starts each automation run on a fresh devbox from the latest
137
- Template box snapshot. The agent sees the automation prompt plus Slack context,
138
- including the triggering message and available Slack thread messages. If Slack
139
- context is incomplete, boxes.dev can start with partial context instead of
140
- waiting forever.
138
+ Template box snapshot for an ordinary project, or the current saved Team
139
+ Template version for a member project. The agent sees the automation prompt
140
+ plus Slack context, including the triggering message and available Slack
141
+ thread messages. If Slack context is incomplete, boxes.dev can start with
142
+ partial context instead of waiting forever.
141
143
 
142
144
  Separate Slack threads or DMs can start separate automation runs at the same
143
145
  time, subject to awake devbox capacity. If Slack retries the same event,
144
146
  boxes.dev reuses the already linked automation run instead of starting a
145
147
  duplicate.
146
148
 
147
- Slack receives a started reply with a link to the boxes.dev thread. When a
149
+ By default, Slack receives a started reply with a link to the boxes.dev thread. When a
148
150
  teammate starts a thread in your workspace, the reply names you and boxes.dev
149
151
  sends you a direct message with links to the source Slack message and new
150
152
  boxes.dev thread. If final Slack replies are enabled, boxes.dev posts the
151
153
  agent's final answer back into the same Slack thread or DM.
152
154
 
155
+ To return to the original Slack conversation from the desktop workbench, click
156
+ the Slack icon beside the thread title. Hover over it to see **Open Slack thread**.
157
+
158
+ ## Choose What Appears In Slack
159
+
160
+ In the automation editor, **What should boxes.dev post in the Slack thread?**
161
+ controls reactions, started messages, attachment warnings, follow-up
162
+ confirmations, and replies when a run ends. Choose each separately for
163
+ **Internal** conversations and **Slack Connect** channels. Use **All** or
164
+ **None** above a column to change that audience together, then adjust individual
165
+ checkboxes. For quiet customer channels, choose **None** under **Slack Connect**.
166
+
167
+ **Include the full agent response** applies when replies at the end of a run
168
+ are enabled. Leave it off for a short status and link. It starts off for Slack
169
+ Connect. Turning off the parent reply keeps the full-response choice for later.
170
+
171
+ The location menu still decides where new runs can start. The Slack Connect
172
+ column appears when that location can include shared channels; hiding the
173
+ column keeps its saved choices. Attachment warnings can remain on even when
174
+ started messages or follow-up confirmations are off.
175
+
176
+ Changes apply to new Slack threads. Existing linked threads keep the choices
177
+ they started with. These settings control automatic activity for this
178
+ automation; help and replies before boxes.dev can identify an automation are
179
+ separate. Turning activity off does not send replacement DMs. The existing DM
180
+ to an owner when a teammate starts work in their workspace is unchanged.
181
+
153
182
  ## Follow-Ups And Controls
154
183
 
155
184
  After a Slack request starts a boxes.dev thread, mention `@boxes.dev` again in
@@ -167,7 +196,8 @@ Use Slack controls in the linked thread:
167
196
  - `@boxes.dev !cancel` cancels queued Slack follow-ups when possible.
168
197
 
169
198
  If the linked devbox is sleeping, boxes.dev may queue the follow-up while the
170
- runtime wakes. If capacity is full, Slack replies with guidance.
199
+ runtime wakes. If capacity is full, Slack replies with guidance when follow-up
200
+ confirmations are enabled.
171
201
 
172
202
  ## Slack Files
173
203
 
@@ -191,8 +221,9 @@ Limits and rules:
191
221
  omitted.
192
222
 
193
223
  An omitted file does not stop an otherwise valid request or linked follow-up.
194
- boxes.dev continues with every file that imported successfully, explains the
195
- omission in Slack, and tells the agent which intended input was not delivered.
224
+ boxes.dev continues with every file that imported successfully and tells the
225
+ agent which intended input was not delivered. It also explains the omission
226
+ in Slack when attachment warnings are enabled.
196
227
  If the work depends on an omitted file, attach it manually in the boxes.dev
197
228
  thread.
198
229
 
@@ -209,11 +240,10 @@ Slack integration home to reach that editor.
209
240
  Slack-triggered automations reply to their original Slack thread or DM when
210
241
  final replies are enabled.
211
242
 
212
- In a channel shared with another organization, boxes.dev replies with only a
213
- link to the finished boxes.dev thread. To let the agent's full response and
214
- failure text appear there too, turn on **Also post the full response in Slack
215
- Connect channels** in the automation's editor. That setting starts off, and it
216
- does not change replies in your own workspace's channels and DMs.
243
+ In a channel shared with another organization, enabled completion replies
244
+ default to a short status and link. To include the agent's response and failure
245
+ text, turn on **Include the full agent response** in the **Slack Connect**
246
+ column. The **Internal** column controls replies in your own workspace.
217
247
 
218
248
  Manual, scheduled, and API automations can separately send selected events to
219
249
  Slack channels or linked-user DMs. Those output destinations can receive final
@@ -72,6 +72,9 @@ Tailscale integration page. boxes.dev uses the team connection to confirm that:
72
72
  - Tailscale policy gives that user, directly or through a group, effective
73
73
  access to the configured tag.
74
74
 
75
+ After verification succeeds, choose **Enable Tailscale** to enable the project.
76
+ Verification alone does not enable the integration.
77
+
75
78
  This verification uses Tailscale's policy engine, so direct users, groups,
76
79
  SCIM-synced groups, wildcards, and autogroups continue to be managed in
77
80
  Tailscale. GitHub-only and passkey-only Tailscale login names are not supported