@boxes-dev/dvb-runtime 1.0.1097 → 1.0.1099
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/agent-init-guides/flow.md +31 -4
- package/dist/agent-init-guides/git-ssh.md +2 -2
- package/dist/agent-init-guides/manifest.md +10 -2
- package/dist/agent-init-guides/running.md +8 -3
- package/dist/agent-init-guides/untracked.md +29 -4
- package/dist/bin/dvb.mjs +108 -27
- package/dist/bin/dvbd.mjs +10 -9
- package/dist/product-docs/references/agent-tools.md +6 -7
- package/dist/product-docs/references/automations.md +4 -4
- package/dist/product-docs/references/aws.md +17 -11
- package/dist/product-docs/references/billing-and-limits.md +23 -11
- package/dist/product-docs/references/cli.md +14 -15
- package/dist/product-docs/references/core-concepts.md +35 -30
- package/dist/product-docs/references/desktop-workbench.md +26 -25
- package/dist/product-docs/references/files-git-and-review.md +20 -17
- package/dist/product-docs/references/fork-workflows.md +44 -31
- package/dist/product-docs/references/getting-started.md +7 -8
- package/dist/product-docs/references/glossary.md +46 -22
- package/dist/product-docs/references/google-cloud.md +13 -8
- package/dist/product-docs/references/index.md +18 -16
- package/dist/product-docs/references/linear.md +2 -2
- package/dist/product-docs/references/managed-environment-files.md +1 -1
- package/dist/product-docs/references/member-managed-files.md +4 -4
- package/dist/product-docs/references/mobile.md +23 -18
- package/dist/product-docs/references/onbox-agent-tools.md +25 -26
- package/dist/product-docs/references/ports-terminal-and-runtime.md +27 -28
- package/dist/product-docs/references/project-setup.md +36 -16
- package/dist/product-docs/references/security-and-data.md +10 -10
- package/dist/product-docs/references/slack.md +3 -3
- package/dist/product-docs/references/tailscale.md +2 -2
- package/dist/product-docs/references/team-template.md +22 -22
- package/dist/product-docs/references/template-box-environment.md +7 -3
- package/dist/product-docs/references/threads-and-agents.md +79 -31
- package/dist/product-docs/references/troubleshooting.md +24 -25
- package/package.json +2 -2
|
@@ -108,15 +108,20 @@ user signs out of Company SSO, and they never need reconnecting.
|
|
|
108
108
|
|
|
109
109
|
With either method, AWS setup does not change the repository and does not
|
|
110
110
|
require a Template box snapshot. New terminals start with
|
|
111
|
-
`AWS_PROFILE=boxes-dev
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
111
|
+
`AWS_PROFILE=boxes-dev`, and open Bash terminals pick up connecting, changing,
|
|
112
|
+
or removing AWS at their next prompt. A terminal that was already waiting for a
|
|
113
|
+
command runs its next command with the old settings, so press Enter once first.
|
|
114
|
+
Values the user set in the shell stay unchanged. Existing Codex and Claude
|
|
115
|
+
sessions keep current work running, then pick up AWS before their next turn:
|
|
116
|
+
boxes.dev refreshes their idle agent process after its work drains. This also
|
|
117
|
+
applies to Claude sessions opened from mobile. Programs that are already running,
|
|
118
|
+
including ones started from a terminal, keep the environment they started
|
|
119
|
+
with. Devbox startup and teardown scripts and Template box maintenance scripts
|
|
120
|
+
receive the same defaults as a new terminal.
|
|
116
121
|
|
|
117
122
|
For a connected project, boxes.dev manages an AWS profile named `boxes-dev` on
|
|
118
|
-
its real machines. That means the Template box and devboxes in an
|
|
119
|
-
project, and the assigned devboxes in a
|
|
123
|
+
its real machines. That means the Template box and devboxes in an independent
|
|
124
|
+
project, and the assigned devboxes in a managed project. A project
|
|
120
125
|
can also have named managed profiles such as `boxes-staging` and
|
|
121
126
|
`boxes-production`. Each one uses its own Company SSO account and permission set
|
|
122
127
|
or its own access key. New terminals and commands in newly started or safely
|
|
@@ -246,10 +251,11 @@ and SDK processes use the new key once it reaches the box, but a long-running
|
|
|
246
251
|
process that already loaded the old key keeps using it until it restarts. The
|
|
247
252
|
old key stays active in AWS, so deactivate it there after nothing needs it.
|
|
248
253
|
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
254
|
+
Terminals use a changed default after it reaches their machine: new ones
|
|
255
|
+
immediately and open ones at their next prompt. Existing Codex and Claude
|
|
256
|
+
sessions preserve current work and pick up managed-profile changes before their
|
|
257
|
+
next turn at the idle boundary described above. User-managed processes that are
|
|
258
|
+
already running keep their prior environment.
|
|
253
259
|
Temporary Company SSO credentials already held in any process remain usable
|
|
254
260
|
until their AWS expiration, and an access key held in any process remains
|
|
255
261
|
usable until it is deactivated in AWS.
|
|
@@ -13,12 +13,15 @@ Current self-serve plans are:
|
|
|
13
13
|
|
|
14
14
|
- Trial: $0, 20 free box-hours, Template box plus 2 awake devboxes, up to 2
|
|
15
15
|
projects.
|
|
16
|
-
- Starter: $19 per paid seat per month,
|
|
17
|
-
Template box plus 4 awake devboxes, up to 5 projects, prepaid overage at $0.
|
|
16
|
+
- Starter: $19 per paid seat per month, 50 included box-hours per user,
|
|
17
|
+
Template box plus 4 awake devboxes, up to 5 projects, prepaid overage at $0.60
|
|
18
18
|
per extra box-hour.
|
|
19
19
|
- Pro: $99 per paid seat per month, 250 included box-hours per user,
|
|
20
20
|
Template box plus 10 awake devboxes, up to 10 projects, prepaid overage at
|
|
21
21
|
$0.60 per extra box-hour.
|
|
22
|
+
- Max: $249 per paid seat per month, 600 included box-hours per user,
|
|
23
|
+
Template box plus 20 awake devboxes, up to 20 projects, prepaid overage at
|
|
24
|
+
$0.60 per extra box-hour.
|
|
22
25
|
|
|
23
26
|
Team and enterprise arrangements may differ from these self-serve limits.
|
|
24
27
|
Included box-hours, project limits, and awake-devbox limits apply per user;
|
|
@@ -44,7 +47,7 @@ GiB. This weighted usage applies to both included usage and prepaid overage
|
|
|
44
47
|
credits. A team resource change applies to newly created Template boxes; it
|
|
45
48
|
does not resize existing boxes.
|
|
46
49
|
|
|
47
|
-
Awake Template boxes and awake devboxes consume box-hours. Sleeping
|
|
50
|
+
Awake Template boxes and awake devboxes consume box-hours. Sleeping boxes do
|
|
48
51
|
not consume active box-hours while they are asleep. Idle devboxes can sleep
|
|
49
52
|
automatically, and users can also sleep devboxes manually. boxes.dev internal
|
|
50
53
|
maintenance wakes on a user's existing devbox do not consume box-hours. The
|
|
@@ -55,10 +58,10 @@ machine uses that admin's box-hours. The Team Template's clean shared source is
|
|
|
55
58
|
normally asleep. Its brief maintenance and boxes.dev update wakes are
|
|
56
59
|
attributed to a team admin for usage; they do not create a project or consume a
|
|
57
60
|
member's devbox slot. A project created from the active Team Template release
|
|
58
|
-
uses a normal project slot and the creating member's normal
|
|
61
|
+
uses a normal project slot and the creating member's normal box
|
|
59
62
|
entitlement.
|
|
60
63
|
|
|
61
|
-
A
|
|
64
|
+
A managed project has no personal Template box to bill. Its idle
|
|
62
65
|
prepared devboxes stay sleeping and do not use box-hours or awake-devbox
|
|
63
66
|
capacity. After a prepared devbox is assigned and wakes for the member, it is
|
|
64
67
|
accounted for exactly like that member's other devboxes.
|
|
@@ -107,23 +110,31 @@ tell the member to contact a team admin.
|
|
|
107
110
|
|
|
108
111
|
## Overage Credits
|
|
109
112
|
|
|
110
|
-
Paid-plan overage uses prepaid usage credits. Team admins on an active Starter
|
|
111
|
-
or
|
|
112
|
-
to what the team can still buy this month, including cents, or pick $20, $
|
|
113
|
-
$
|
|
113
|
+
Paid-plan overage uses prepaid usage credits. Team admins on an active Starter,
|
|
114
|
+
Pro, or Max plan can buy credits from billing. They can enter any amount from $20 up
|
|
115
|
+
to what the team can still buy this month, including cents, or pick $20, $100,
|
|
116
|
+
$250, or $500 to fill in the amount. A trial team needs to choose a paid plan
|
|
114
117
|
before it can buy credits.
|
|
115
118
|
|
|
116
|
-
A team can
|
|
117
|
-
|
|
119
|
+
A team can spend up to $1,000 on credits per calendar month on Starter, Pro,
|
|
120
|
+
or Max, counting manual purchases and auto-reload together. Months follow
|
|
118
121
|
UTC. Purchased credits carry over to later months. Billing shows how much the
|
|
119
122
|
team can still buy this month and blocks larger amounts. A checkout that was
|
|
120
123
|
opened but not paid holds its amount for about 30 minutes. Teams that need more
|
|
121
124
|
credits can email hi@boxes.dev.
|
|
122
125
|
|
|
126
|
+
Each purchase receives a discount based on the amount paid: 5% from $100,
|
|
127
|
+
7.5% from $250, and 10% from $500. The discount applies to the whole purchase.
|
|
128
|
+
For example, paying $100 adds $105.26 in credits, $250 adds $270.27, and $500
|
|
129
|
+
adds $555.55. Credit is rounded down to cents. Monthly limits count money
|
|
130
|
+
spent, not the extra credit received. These shared credits also pay for mobile
|
|
131
|
+
devices and builders.
|
|
132
|
+
|
|
123
133
|
Team admins can turn on auto-reload. Auto-reload buys the configured reload
|
|
124
134
|
amount when the credit balance reaches a configured threshold. An optional
|
|
125
135
|
monthly auto-reload limit caps automatic purchases only; with no limit set,
|
|
126
136
|
auto-reload can continue up to the team's monthly credit purchase limit.
|
|
137
|
+
The same bulk discount applies to each reload based on its payment amount.
|
|
127
138
|
|
|
128
139
|
If credits are low, the product warns users. If credits are depleted and the
|
|
129
140
|
team is past included usage, compute can be blocked until a team admin buys
|
|
@@ -155,6 +166,7 @@ Self-serve plans also limit projects:
|
|
|
155
166
|
- Trial: up to 2 projects.
|
|
156
167
|
- Starter: up to 5 projects.
|
|
157
168
|
- Pro: up to 10 projects.
|
|
169
|
+
- Max: up to 20 projects.
|
|
158
170
|
|
|
159
171
|
If a user reaches their project limit, setting up another project is blocked. The
|
|
160
172
|
user should delete a project, upgrade if available, or contact
|
|
@@ -165,7 +165,7 @@ contents. Timeout flags accept 1–120 seconds. Clear flags remove a script.
|
|
|
165
165
|
Always read first and use its revision. If the revision changed, read again and
|
|
166
166
|
reconcile the newer settings.
|
|
167
167
|
|
|
168
|
-
For an
|
|
168
|
+
For an independent project with a personal Template box, the agent can design one
|
|
169
169
|
maintenance script and its complete GitHub watch set together:
|
|
170
170
|
|
|
171
171
|
```bash
|
|
@@ -182,7 +182,7 @@ paths, whether each watch is enabled, and exact repository-relative files or
|
|
|
182
182
|
directories. Paths are not globs. Omitting an editable existing watch requires
|
|
183
183
|
`--confirm-watch-removals`. The command preserves the repeating schedule and
|
|
184
184
|
does not start a run; new or changed watches begin from a fresh default-branch
|
|
185
|
-
baseline.
|
|
185
|
+
baseline. Managed projects support lifecycle editing but return
|
|
186
186
|
`template_maintenance_unavailable` for maintenance because they have no
|
|
187
187
|
personal Template box.
|
|
188
188
|
|
|
@@ -243,7 +243,7 @@ Use:
|
|
|
243
243
|
dvb connect <devbox>
|
|
244
244
|
```
|
|
245
245
|
|
|
246
|
-
This opens or attaches to a persistent terminal session on the selected
|
|
246
|
+
This opens or attaches to a persistent terminal session on the selected box.
|
|
247
247
|
You can name sessions, reconnect to them later, or run one command:
|
|
248
248
|
|
|
249
249
|
```bash
|
|
@@ -273,8 +273,7 @@ dvb agents [project] [--json | --bell]
|
|
|
273
273
|
```
|
|
274
274
|
|
|
275
275
|
This opens a live terminal switchboard for existing agent threads on the
|
|
276
|
-
project's devboxes and, when it has one, its Template box. A
|
|
277
|
-
member project has only its Devboxes section and shows any recoverable setup
|
|
276
|
+
project's devboxes and, when it has one, its Template box. A managed project has only its Devboxes section and shows any recoverable setup
|
|
278
277
|
warning without inventing a Template target. If the project is omitted and more than one
|
|
279
278
|
is available, choose one from the prompt. If there are no projects yet, the CLI
|
|
280
279
|
points you to the coding-agent-led `dvb agent-init` flow or desktop setup.
|
|
@@ -323,8 +322,8 @@ Use `p` to pin or unpin an eligible Template-box thread or devbox anchor, `r`
|
|
|
323
322
|
to rename a thread, and `x` to archive or restore it. On a devbox group row,
|
|
324
323
|
`r` renames the devbox instead, and empty input returns the group to its first
|
|
325
324
|
thread's title. On an archived
|
|
326
|
-
cold-storage thread, `x` opens the available restore choice.
|
|
327
|
-
can use the current Template box or a new devbox;
|
|
325
|
+
cold-storage thread, `x` opens the available restore choice. Independent projects
|
|
326
|
+
can use the current Template box or a new devbox; managed projects
|
|
328
327
|
restore only to a new devbox. Empty rename input
|
|
329
328
|
returns the automatic title. Codex archive updates the saved native session
|
|
330
329
|
before the shared list; Claude archive changes the shared list without waking
|
|
@@ -332,8 +331,8 @@ its machine. If an action is not safe for the selected row, the switchboard
|
|
|
332
331
|
explains why.
|
|
333
332
|
|
|
334
333
|
Press `n` to start a thread on the selected item's machine. Select a thread on
|
|
335
|
-
the Template box or a devbox group/thread. In an
|
|
336
|
-
targets the Template box. A
|
|
334
|
+
the Template box or a devbox group/thread. In an independent empty project, `n`
|
|
335
|
+
targets the Template box. A managed project has no Template
|
|
337
336
|
target. Press `N` to start a thread on a new devbox created from the project's
|
|
338
337
|
current reusable source. The compact composer shows its target in the
|
|
339
338
|
border and the current agent settings on one status line. Press `Tab` (or
|
|
@@ -434,9 +433,9 @@ message there. If the project is omitted, the CLI auto-selects the only project
|
|
|
434
433
|
or shows the same project picker as `dvb agents`.
|
|
435
434
|
|
|
436
435
|
When starting a new thread without `--devbox`, the command creates a devbox from
|
|
437
|
-
the project's current reusable source. For an
|
|
436
|
+
the project's current reusable source. For an independent project, that is the
|
|
438
437
|
latest completed Template-box snapshot; if none exists, the command asks you to
|
|
439
|
-
take one without creating a thread or devbox. For a
|
|
438
|
+
take one without creating a thread or devbox. For a managed
|
|
440
439
|
project, it uses the current saved version and any prepared devbox. With
|
|
441
440
|
`--devbox`, it uses that existing devbox in the selected project; a reusable
|
|
442
441
|
source is not required and deleting the new thread never deletes that devbox.
|
|
@@ -573,7 +572,7 @@ Use:
|
|
|
573
572
|
dvb cp <local-path> <devbox>:<remote-path>
|
|
574
573
|
```
|
|
575
574
|
|
|
576
|
-
`dvb cp` copies local files or directories into the selected
|
|
575
|
+
`dvb cp` copies local files or directories into the selected box. Relative
|
|
577
576
|
remote paths resolve against the remote project working directory.
|
|
578
577
|
|
|
579
578
|
For full file browsing, downloads, inline review, and Git review, use the
|
|
@@ -666,7 +665,7 @@ for adding the pinning step to an application.
|
|
|
666
665
|
|
|
667
666
|
## Snapshots, Devbox Creation, Sleep, Wake, And Reset
|
|
668
667
|
|
|
669
|
-
For an
|
|
668
|
+
For an independent project's Template box, use:
|
|
670
669
|
|
|
671
670
|
```bash
|
|
672
671
|
dvb checkpoint <template-box>
|
|
@@ -674,7 +673,7 @@ dvb checkpoint <template-box>
|
|
|
674
673
|
|
|
675
674
|
to capture a new snapshot of the Template box.
|
|
676
675
|
|
|
677
|
-
|
|
676
|
+
Managed projects have no personal Template box, so checkpoint and
|
|
678
677
|
other Template-only commands are not available for them. Their team admins save
|
|
679
678
|
new versions through the Team Template editor.
|
|
680
679
|
|
|
@@ -710,7 +709,7 @@ later; destroy removes it.
|
|
|
710
709
|
|
|
711
710
|
## Services, IDE, SSH, And Mounts
|
|
712
711
|
|
|
713
|
-
`dvb services` manages user services running on the selected
|
|
712
|
+
`dvb services` manages user services running on the selected box. System
|
|
714
713
|
services owned by boxes.dev are hidden from normal service management.
|
|
715
714
|
|
|
716
715
|
`dvb ide` prepares and opens remote editor access. `dvb ssh proxy` supports the
|
|
@@ -11,6 +11,10 @@ projects without personal Template boxes; those projects still own their
|
|
|
11
11
|
devboxes, threads, settings, and integrations. Set up another project when a
|
|
12
12
|
different codebase needs its own environment.
|
|
13
13
|
|
|
14
|
+
An **independent project** has its own Template box. A **managed project** uses
|
|
15
|
+
a Team Template and has no Template box of its own. Team members can own either
|
|
16
|
+
type. See `glossary.md` for older names and aliases.
|
|
17
|
+
|
|
14
18
|
## Team Template
|
|
15
19
|
|
|
16
20
|
A Team Template is one named, team-wide, versioned starting environment for new
|
|
@@ -18,15 +22,15 @@ projects. It is not a project's Template box. A team can have several Team
|
|
|
18
22
|
Templates for different project shapes. Each has its own release history and
|
|
19
23
|
editing lock. Team admins publish releases, and current team members can create
|
|
20
24
|
independent projects from a selected template's active saved version without
|
|
21
|
-
supplying a local repository. A Team Template can create an
|
|
22
|
-
with its own Template box or a
|
|
25
|
+
supplying a local repository. A Team Template can create an independent project
|
|
26
|
+
with its own Template box or a managed project whose future devboxes keep using
|
|
23
27
|
the Team Template's current saved files. See `team-template.md` for the editing,
|
|
24
28
|
saved-version, setup, Git access, and copied-data workflow.
|
|
25
29
|
|
|
26
30
|
## Template box
|
|
27
31
|
|
|
28
|
-
The Template box is the persistent base machine for an
|
|
29
|
-
the source that future devboxes start from.
|
|
32
|
+
The Template box is the persistent base machine for an independent project. It is
|
|
33
|
+
the source that future devboxes start from. Managed projects do
|
|
30
34
|
not have one.
|
|
31
35
|
|
|
32
36
|
Use the Template box for:
|
|
@@ -42,7 +46,7 @@ is intentionally part of the shared baseline.
|
|
|
42
46
|
## Devbox
|
|
43
47
|
|
|
44
48
|
A devbox is an isolated machine created from the project's reusable source: an
|
|
45
|
-
|
|
49
|
+
independent project's Template-box snapshot or a managed project's current Team
|
|
46
50
|
Template saved version. Each devbox has its own filesystem, services, memory,
|
|
47
51
|
local app state, terminal sessions, ports, and agent threads.
|
|
48
52
|
|
|
@@ -53,8 +57,8 @@ project uses, then sleep or destroy devboxes you no longer need.
|
|
|
53
57
|
|
|
54
58
|
## Thread
|
|
55
59
|
|
|
56
|
-
A thread is a conversation with a coding agent connected to a
|
|
57
|
-
boxes.dev, threads run on a devbox or, in an
|
|
60
|
+
A thread is a conversation with a coding agent connected to a box. In
|
|
61
|
+
boxes.dev, threads run on a devbox or, in an independent project, on the Template
|
|
58
62
|
box.
|
|
59
63
|
|
|
60
64
|
The agent is Codex or Claude, depending on what is enabled and authenticated.
|
|
@@ -62,26 +66,25 @@ In the desktop app, GUI and the CLI are two views of that same conversation,
|
|
|
62
66
|
not separate thread types. A thread may be user-started, setup-created, or
|
|
63
67
|
spawned by an automation or integration.
|
|
64
68
|
|
|
65
|
-
##
|
|
69
|
+
## Selected box
|
|
66
70
|
|
|
67
|
-
A
|
|
68
|
-
|
|
69
|
-
the app.
|
|
71
|
+
A box is a devbox or Template box. The selected box is the one currently chosen
|
|
72
|
+
in the desktop app.
|
|
70
73
|
|
|
71
|
-
The selected
|
|
72
|
-
status, wake/sleep controls, and
|
|
74
|
+
The selected box matters because terminals, forwarded ports, file views, git
|
|
75
|
+
status, wake/sleep controls, and box usage indicators follow it. If a user
|
|
73
76
|
selects a devbox, those tools operate on the devbox. If the user selects the
|
|
74
|
-
Template box, they operate on the Template box.
|
|
77
|
+
Template box, they operate on the Template box. Port forwarding follows
|
|
78
|
+
selection by default, but can stay on one box when pinned.
|
|
75
79
|
|
|
76
80
|
## Snapshot
|
|
77
81
|
|
|
78
|
-
A snapshot is a saved state of an
|
|
82
|
+
A snapshot is a saved state of an independent project's Template box that future
|
|
79
83
|
devboxes can start from. A snapshot preserves the saved filesystem, local
|
|
80
84
|
development data, and memory. Apps that run independently of agents and
|
|
81
85
|
terminals, such as Docker containers and system services, keep running on new
|
|
82
86
|
devboxes. Copied agents, terminals, and processes started from them do not
|
|
83
|
-
continue, and background services from setup start again. Team Template
|
|
84
|
-
member projects use the Team Template's current saved version instead; team
|
|
87
|
+
continue, and background services from setup start again. Managed projects use the Team Template's current saved version instead; team
|
|
85
88
|
admins update it from the Team Template editor.
|
|
86
89
|
|
|
87
90
|
Take a new snapshot after updating the Template box in a way future devboxes
|
|
@@ -94,7 +97,7 @@ From a Template box terminal or coding-agent session, run:
|
|
|
94
97
|
dvb-onbox snapshot
|
|
95
98
|
```
|
|
96
99
|
|
|
97
|
-
This does the same thing as **New snapshot** in the
|
|
100
|
+
This does the same thing as **New snapshot** in the box menu. The command
|
|
98
101
|
waits through the brief capture window and reports the new snapshot ID after
|
|
99
102
|
the machine reconnects. If Codex or Claude is running, boxes.dev will resume
|
|
100
103
|
that work only on the Template box; future devboxes will receive the saved
|
|
@@ -111,20 +114,22 @@ snapshot and then create the devbox.
|
|
|
111
114
|
|
|
112
115
|
## Checkpoint
|
|
113
116
|
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
+
The active workstation CLI command `dvb checkpoint <template-box>` takes a
|
|
118
|
+
Template box snapshot. From the Template box itself, use `dvb-onbox snapshot`.
|
|
119
|
+
Prefer snapshot when describing the saved state, and preserve checkpoint in
|
|
120
|
+
the exact CLI invocation. This alias does not refer to a separate product
|
|
121
|
+
feature.
|
|
117
122
|
|
|
118
123
|
## Awake, Sleeping, And Waking
|
|
119
124
|
|
|
120
|
-
Awake
|
|
121
|
-
Sleeping
|
|
122
|
-
instead of restarting it, but they do not run commands or consume awake
|
|
125
|
+
Awake boxes can run commands, serve ports, and accept live agent work.
|
|
126
|
+
Sleeping boxes retain their machine state in memory, like sleeping a laptop
|
|
127
|
+
instead of restarting it, but they do not run commands or consume awake box
|
|
123
128
|
capacity. Waking is the transition from sleeping back to running.
|
|
124
129
|
|
|
125
|
-
The desktop app shows
|
|
130
|
+
The desktop app shows box states such as Running, Connected, Sleeping,
|
|
126
131
|
Waking, Connecting, Upgrading, Snapshotting, and Disconnected depending on the
|
|
127
|
-
selected
|
|
132
|
+
selected box and current operation.
|
|
128
133
|
|
|
129
134
|
## Awake Devbox Limit
|
|
130
135
|
|
|
@@ -134,12 +139,12 @@ it can be woken when the awake devbox limit is reached.
|
|
|
134
139
|
|
|
135
140
|
## Template box Snapshots Versus Devbox Work
|
|
136
141
|
|
|
137
|
-
For an
|
|
138
|
-
For a
|
|
142
|
+
For an independent project, the Template box is the source of future devbox state.
|
|
143
|
+
For a managed project, the shared Team Template saved version is
|
|
139
144
|
the source. A devbox is where a specific task should happen. If useful setup
|
|
140
|
-
was discovered while working on an
|
|
145
|
+
was discovered while working on an independent-project devbox, apply that setup to
|
|
141
146
|
the Template box and take a new snapshot only when future devboxes should
|
|
142
|
-
inherit it. For a
|
|
147
|
+
inherit it. For a managed project, ask a team admin to update the Team Template
|
|
143
148
|
when the shared baseline should change.
|
|
144
149
|
|
|
145
150
|
Do not assume changes made on a devbox automatically update the Template box or
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
The desktop workbench is the main boxes.dev workspace. It is where you switch
|
|
4
4
|
projects, read and start agent threads, open files and Git, use the terminal,
|
|
5
5
|
use the shared Browser, open forwarded ports, and wake or sleep the selected
|
|
6
|
-
|
|
6
|
+
box.
|
|
7
7
|
|
|
8
8
|
## The Main Areas
|
|
9
9
|
|
|
@@ -21,7 +21,7 @@ The workbench has a few persistent areas:
|
|
|
21
21
|
thread is selected and hidden when the left pane
|
|
22
22
|
is too narrow to fit it. A thread inside a collapsed automation stays hidden
|
|
23
23
|
until you expand that automation. The
|
|
24
|
-
content pane's title bar starts with
|
|
24
|
+
content pane's title bar starts with box status, metrics, and ports when
|
|
25
25
|
a Template box or devbox is selected, and ends with the
|
|
26
26
|
Terminal/Files/Git/Review/Browser pane control as icon-only buttons that show
|
|
27
27
|
their names on hover; update notices appear in the middle when available.
|
|
@@ -59,8 +59,8 @@ The titlebar pane control switches the aux pane between Terminal, Files,
|
|
|
59
59
|
Git/Review, and Browser. The app menu can show or hide the Agent pane. At least
|
|
60
60
|
one main area stays visible. A new devbox starts with no aux pane open. The
|
|
61
61
|
Template box and each devbox then remember their last aux-pane choice
|
|
62
|
-
independently, so returning to a
|
|
63
|
-
can be resized. Showing Terminal reattaches the
|
|
62
|
+
independently, so returning to a box restores its previous pane. Pane widths
|
|
63
|
+
can be resized. Showing Terminal reattaches the box's open terminal
|
|
64
64
|
sessions, or starts one if it has none, and closing the last terminal tab
|
|
65
65
|
closes the pane.
|
|
66
66
|
|
|
@@ -223,7 +223,7 @@ row to return it to the default.
|
|
|
223
223
|
Use the project selector in the titlebar to switch between projects on the same
|
|
224
224
|
desktop app account. Threads and devboxes are shown for the selected project.
|
|
225
225
|
Most projects have one Template box. A project created through a Team
|
|
226
|
-
Template's **
|
|
226
|
+
Template's **managed projects** mode has no personal Template box and omits that
|
|
227
227
|
row without changing its normal thread and devbox workflow.
|
|
228
228
|
|
|
229
229
|
Use **New project...** in the project selector to add another project. On
|
|
@@ -254,8 +254,8 @@ through **New project...** instead of this admin-only management menu.
|
|
|
254
254
|
Project settings, integrations, automations, and a teammate's shared thread do
|
|
255
255
|
not select one of your Template boxes or devboxes. On those pages, machine
|
|
256
256
|
status and workspace tools are hidden and the workbench does not wake the
|
|
257
|
-
machine you last used. Return to one of your own
|
|
258
|
-
available, the Template box when you want
|
|
257
|
+
machine you last used. Return to one of your own threads connected to a box or, when
|
|
258
|
+
available, the Template box when you want box controls and Files,
|
|
259
259
|
Git/Review, Terminal, Browser, or Ports.
|
|
260
260
|
|
|
261
261
|
The app menu also includes **Project settings**, **Desktop app settings...**,
|
|
@@ -264,24 +264,24 @@ Configure agents can save multiple Codex and Claude accounts or API keys and
|
|
|
264
264
|
choose one active credential for each agent across all devboxes. The File menu
|
|
265
265
|
also includes **Delete This Project**.
|
|
266
266
|
|
|
267
|
-
##
|
|
267
|
+
## Box status
|
|
268
268
|
|
|
269
|
-
The
|
|
269
|
+
The box status control describes the selected box, which may be the
|
|
270
270
|
Template box or a devbox depending on the selected thread. It can show states
|
|
271
271
|
such as running, sleeping, waking, snapshotting, migration or repair needed, and
|
|
272
272
|
related errors.
|
|
273
273
|
|
|
274
|
-
Use the status control to wake or sleep the selected
|
|
274
|
+
Use the status control to wake or sleep the selected box when those actions
|
|
275
275
|
are available. Its auto-wake setting controls whether a sleeping Template box or
|
|
276
276
|
devbox wakes when you return to it; when auto-wake is off, use an explicit Wake
|
|
277
277
|
action instead.
|
|
278
278
|
|
|
279
279
|
Three small CPU, memory, and disk meters show live utilization for the selected
|
|
280
|
-
|
|
280
|
+
box. CPU and memory fill colors highlight elevated load. The disk meter
|
|
281
281
|
turns yellow below 2 GiB free and red below 1 GiB free. Hover the meters for
|
|
282
282
|
exact resource details, or click them to open an Activity Monitor-style view of
|
|
283
|
-
processes on the
|
|
284
|
-
|
|
283
|
+
processes on the box. Empty tracks remain visible while the selected
|
|
284
|
+
box has no live metrics.
|
|
285
285
|
|
|
286
286
|
## Project Settings
|
|
287
287
|
|
|
@@ -298,7 +298,7 @@ To change the automatic idle-sleep timeout, open **Account
|
|
|
298
298
|
→ Sleep timeout** and choose 5, 15, 30, or 60 minutes, or **Team default**.
|
|
299
299
|
Team admins can set the default in **Team settings → Sleep timeout**; without
|
|
300
300
|
a custom setting it is five minutes. Your choice overrides the team default
|
|
301
|
-
for your Template boxes and devboxes, including
|
|
301
|
+
for your Template boxes and devboxes, including managed projects.
|
|
302
302
|
Changes apply to existing and new boxes. A running box may keep its current
|
|
303
303
|
sleep deadline until its next activity; saving will not wake a sleeping box.
|
|
304
304
|
Longer timeouts use more box-hours; active agents can still keep boxes awake.
|
|
@@ -314,11 +314,12 @@ keyboard shortcuts, account, billing, team, update, and log-out actions.
|
|
|
314
314
|
For a project that has one, the Template box page is for the project's exact
|
|
315
315
|
Template machine. Use it to manage snapshots, repositories, maintenance, or
|
|
316
316
|
the machine itself; open its terminal, inspect files or Git, or check whether
|
|
317
|
-
it is awake.
|
|
317
|
+
it is awake. Managed projects omit the page and its thread,
|
|
318
318
|
snapshot, repository, terminal, and power controls.
|
|
319
319
|
|
|
320
320
|
Under **Project**, select the **Template box** row's title to open its page.
|
|
321
|
-
The chevron expands its threads, including pinned and
|
|
321
|
+
The chevron expands its threads, including pinned conversations and, when it
|
|
322
|
+
has archived ones, an **Archived threads** list.
|
|
322
323
|
Hover or focus the row for **New thread on Template box** and its **…** menu.
|
|
323
324
|
The menu contains terminal, snapshot, and sleep actions.
|
|
324
325
|
|
|
@@ -572,11 +573,11 @@ own Find shortcut when focused.
|
|
|
572
573
|
## Files And Git
|
|
573
574
|
|
|
574
575
|
The Files and Git/Review segments in the titlebar open panes for the selected
|
|
575
|
-
|
|
576
|
+
box. Use Files to browse, search, upload, download, preview, and add
|
|
576
577
|
plain-file review comments. Use Git/Review to inspect repository status, diffs,
|
|
577
578
|
history, review comments, staging, and commits.
|
|
578
579
|
|
|
579
|
-
These panes route to the
|
|
580
|
+
These panes route to the box for the selected thread. If a devbox thread is
|
|
580
581
|
selected, Files and Git/Review inspect that devbox. If the Template box is
|
|
581
582
|
selected, they inspect the Template box.
|
|
582
583
|
|
|
@@ -584,15 +585,15 @@ See `files-git-and-review.md` for the detailed workflow.
|
|
|
584
585
|
|
|
585
586
|
## Browser
|
|
586
587
|
|
|
587
|
-
The Browser pane opens a Chromium session on the selected
|
|
588
|
+
The Browser pane opens a Chromium session on the selected box. It follows
|
|
588
589
|
the same selection model as Files, Git/Review, Terminal, and Ports: Template box
|
|
589
590
|
when the Template box is selected, the selected devbox when a devbox thread is
|
|
590
591
|
selected.
|
|
591
592
|
|
|
592
593
|
Browser tabs, cookies, local storage, downloads, uploads, and other profile
|
|
593
|
-
state live on that
|
|
594
|
+
state live on that box, so the user and agents can share the same web
|
|
594
595
|
session. The Browser pane supports ordinary page interaction, file chooser
|
|
595
|
-
prompts, downloads into the
|
|
596
|
+
prompts, downloads into the box, permission prompts, browser dialogs, and
|
|
596
597
|
profile reset. **Restart browser** asks for confirmation, then opens one blank
|
|
597
598
|
tab while preserving sign-ins and saved profile data. Check **Restore open
|
|
598
599
|
tabs** in that confirmation to reload the current tabs instead; the choice
|
|
@@ -652,7 +653,7 @@ can lose unsaved form entries. Agents use the shared browser skill's
|
|
|
652
653
|
`POST /.sprite/api/browser/restart` route; reading the browser's state alone
|
|
653
654
|
does not restart a disconnected browser.
|
|
654
655
|
|
|
655
|
-
The
|
|
656
|
+
The box has no security key or platform authenticator of its own. In the
|
|
656
657
|
desktop app, Browser-pane passkey forwarding is off by default and can be
|
|
657
658
|
enabled under **Desktop app settings > Browser > Allow sites to use a passkey
|
|
658
659
|
on this computer**. The first eligible passkey request can also ask whether to
|
|
@@ -695,7 +696,7 @@ element geometry.
|
|
|
695
696
|
## Ports
|
|
696
697
|
|
|
697
698
|
The ports control in the titlebar shows a singular or plural count of localhost
|
|
698
|
-
ports detected on the selected
|
|
699
|
+
ports detected on the selected box and forwarded to localhost on your
|
|
699
700
|
computer. You can open browser-friendly ports or copy the local target for other
|
|
700
701
|
tools, such as database clients.
|
|
701
702
|
|
|
@@ -703,7 +704,7 @@ See `ports-terminal-and-runtime.md` for details.
|
|
|
703
704
|
|
|
704
705
|
## Terminal
|
|
705
706
|
|
|
706
|
-
The terminal pane opens shell sessions on the selected
|
|
707
|
+
The terminal pane opens shell sessions on the selected box. It follows the
|
|
707
708
|
same selection model as Files, Git/Review, Browser, and Ports: Template box when
|
|
708
709
|
the Template box is selected, the selected devbox when a devbox thread is
|
|
709
710
|
selected.
|
|
@@ -732,7 +733,7 @@ periodic safety checks still recover a missed notification. Control-plane
|
|
|
732
733
|
authorization lasts at most ten minutes, and a destination's DNS expiry can
|
|
733
734
|
make the effective lease shorter. When the feature or its current policy is
|
|
734
735
|
unavailable and no valid lease is already applied, configured destinations fail
|
|
735
|
-
closed while unrelated
|
|
736
|
+
closed while unrelated box traffic continues normally. A temporary policy
|
|
736
737
|
or hostname refresh problem can preserve the exact already-applied path only
|
|
737
738
|
through its original lease deadline; it does not renew permission, and Team
|
|
738
739
|
Settings may still show temporary unavailability. Routine boxes.dev
|