@boxes-dev/dvb-runtime 1.0.963 → 1.0.964
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/bin/dvb.mjs +160 -63
- package/dist/bin/dvbd.mjs +6 -6
- package/dist/product-docs/references/agent-tools.md +10 -4
- package/dist/product-docs/references/automations.md +14 -11
- package/dist/product-docs/references/aws.md +6 -5
- package/dist/product-docs/references/billing-and-limits.md +13 -5
- package/dist/product-docs/references/cli.md +22 -12
- package/dist/product-docs/references/core-concepts.md +34 -21
- package/dist/product-docs/references/desktop-workbench.md +27 -21
- package/dist/product-docs/references/files-git-and-review.md +46 -22
- package/dist/product-docs/references/fork-workflows.md +42 -15
- package/dist/product-docs/references/getting-started.md +49 -31
- package/dist/product-docs/references/glossary.md +10 -6
- package/dist/product-docs/references/index.md +17 -13
- package/dist/product-docs/references/mobile.md +26 -23
- package/dist/product-docs/references/onbox-agent-tools.md +14 -7
- package/dist/product-docs/references/ports-terminal-and-runtime.md +11 -9
- package/dist/product-docs/references/project-setup.md +29 -17
- package/dist/product-docs/references/security-and-data.md +38 -19
- package/dist/product-docs/references/tailscale.md +15 -11
- package/dist/product-docs/references/team-template.md +129 -82
- package/dist/product-docs/references/template-box-environment.md +10 -8
- package/dist/product-docs/references/threads-and-agents.md +90 -44
- package/dist/product-docs/references/troubleshooting.md +39 -16
- package/package.json +2 -2
|
@@ -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.
|
|
10
|
-
a Template box
|
|
11
|
-
also starts a setup thread
|
|
12
|
-
|
|
13
|
-
|
|
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
|
-
|
|
21
|
-
runs, taking snapshots, maintaining shared project
|
|
22
|
-
setup-oriented questions.
|
|
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
|
-
|
|
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.
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
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
|
-
|
|
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
|
|
59
|
-
|
|
60
|
-
create a new devbox + thread
|
|
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,
|
|
63
|
-
|
|
64
|
-
|
|
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
|
-
|
|
83
|
-
|
|
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.
|
|
102
|
-
|
|
103
|
-
|
|
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
|
|
57
|
-
|
|
58
|
-
|
|
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
|
|
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.
|
|
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
|
|
14
|
-
devboxes from
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
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
|
-
|
|
23
|
-
|
|
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:
|
|
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
|
|
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
|
|
84
|
-
|
|
85
|
-
|
|
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
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
a **New thread on template**.
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
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
|
-
|
|
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
|
|
70
|
-
|
|
71
|
-
from the latest project snapshot or **To Template box** to
|
|
72
|
-
Template-box path.
|
|
73
|
-
|
|
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
|
|
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
|
|
206
|
-
|
|
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
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
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
|
|
165
|
-
ordinary
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
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.
|
|
216
|
-
the Template box
|
|
217
|
-
|
|
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
|
-
|
|
9
|
-
|
|
10
|
-
|
|
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
|
|
155
|
-
|
|
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.
|
|
174
|
-
access
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
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
|
|
273
|
-
still creates exactly one project and one
|
|
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
|
|
673
|
-
environment setup afterwards. Each project
|
|
674
|
-
|
|
675
|
-
|
|
676
|
-
|
|
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
|
|
152
|
-
agents, aliases, extensions, and other same-user code
|
|
153
|
-
on
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
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
|
|
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
|
|
205
|
-
|
|
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
|
|
264
|
-
devboxes, snapshots, and
|
|
265
|
-
|
|
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
|
|
4
|
-
|
|
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
|
|
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
|
|
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
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
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
|