@boxes-dev/dvb-runtime 1.0.1084 → 1.0.1089

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 CHANGED
@@ -1,6 +1,6 @@
1
1
  #!/usr/bin/env node
2
2
 
3
- !function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="4b9bb473-e618-5a79-8a86-c0fdba0f0295")}catch(e){}}();
3
+ !function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="386d2bc5-76f8-5193-be15-c9ac6e87cee9")}catch(e){}}();
4
4
  import { createRequire as __dvbCreateRequire } from "node:module";
5
5
  import { dirname as __dvbDirname } from "node:path";
6
6
  import { fileURLToPath as __dvbFileURLToPath } from "node:url";
@@ -70354,9 +70354,9 @@ var init_sentry = __esm({
70354
70354
  uncaughtExceptionMonitorInstalled = false;
70355
70355
  currentDevboxSentryUser = null;
70356
70356
  readBuildMetadata = () => {
70357
- const rawPackageVersion = "1.0.1084";
70358
- const rawGitSha = "a319822c0c2a00fbd9996f57d13fd01bdec96f73";
70359
- const rawSentryRelease = "boxes-dev-dvb@1.0.1084+a319822c0c2a00fbd9996f57d13fd01bdec96f73";
70357
+ const rawPackageVersion = "1.0.1089";
70358
+ const rawGitSha = "448da6d06b2e5e68b5c74e9346f33f013d5f7870";
70359
+ const rawSentryRelease = "boxes-dev-dvb@1.0.1089+448da6d06b2e5e68b5c74e9346f33f013d5f7870";
70360
70360
  const packageVersion = typeof rawPackageVersion === "string" ? rawPackageVersion : void 0;
70361
70361
  const gitSha = typeof rawGitSha === "string" ? rawGitSha : void 0;
70362
70362
  const sentryRelease = typeof rawSentryRelease === "string" ? rawSentryRelease : void 0;
@@ -75058,10 +75058,10 @@ Important note on imported AWS IAM Identity Center configuration:
75058
75058
  repair it.
75059
75059
  - If the project needs AWS and unqualified \`aws sts get-caller-identity\` does
75060
75060
  not already work, record an actionable item in \`{{setup_todo_path}}\` and the
75061
- final response: open **Integrations \u2192 AWS**, connect the company identity,
75062
- choose the default account and permission set for \`boxes-dev\`, and add named
75063
- managed profiles for any additional access. Validate from a fresh terminal
75064
- after the user connects.
75061
+ final response: open **Integrations \u2192 AWS** and set up the default
75062
+ \`boxes-dev\` profile with Company SSO or an IAM user's access key, then add
75063
+ named managed profiles for any additional access. Validate from a fresh
75064
+ terminal after the user connects.
75065
75065
  - If repository scripts hard-code an imported SSO profile, preserve tracked
75066
75066
  files unless \`agentInstructions\` explicitly authorizes that change. Record
75067
75067
  the exact command and recommended standard-provider-chain change instead.
@@ -75740,7 +75740,7 @@ var init_packageVersion = __esm({
75740
75740
  return path18.join(process.cwd(), "dvb");
75741
75741
  };
75742
75742
  readEmbeddedPackageVersion = () => {
75743
- const raw = "1.0.1084";
75743
+ const raw = "1.0.1089";
75744
75744
  return trimVersion(raw);
75745
75745
  };
75746
75746
  readNearestPackageMetadata = (basePath) => {
@@ -300854,4 +300854,4 @@ react/cjs/react-jsx-runtime.development.js:
300854
300854
  *)
300855
300855
  */
300856
300856
 
300857
- //# debugId=4b9bb473-e618-5a79-8a86-c0fdba0f0295
300857
+ //# debugId=386d2bc5-76f8-5193-be15-c9ac6e87cee9
package/dist/bin/dvbd.mjs CHANGED
@@ -1,6 +1,6 @@
1
1
  #!/usr/bin/env node
2
2
 
3
- !function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="37a3fca6-6f66-5106-99a6-67552067615c")}catch(e){}}();
3
+ !function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="7f4b3604-1af9-5143-b37e-1ae102911c44")}catch(e){}}();
4
4
  import { createRequire as __dvbCreateRequire } from "node:module";
5
5
  import { dirname as __dvbDirname } from "node:path";
6
6
  import { fileURLToPath as __dvbFileURLToPath } from "node:url";
@@ -64675,9 +64675,9 @@ var init_sentry = __esm({
64675
64675
  uncaughtExceptionMonitorInstalled = false;
64676
64676
  currentDevboxSentryUser = null;
64677
64677
  readBuildMetadata = () => {
64678
- const rawPackageVersion = "1.0.1084";
64679
- const rawGitSha = "a319822c0c2a00fbd9996f57d13fd01bdec96f73";
64680
- const rawSentryRelease = "boxes-dev-dvb@1.0.1084+a319822c0c2a00fbd9996f57d13fd01bdec96f73";
64678
+ const rawPackageVersion = "1.0.1089";
64679
+ const rawGitSha = "448da6d06b2e5e68b5c74e9346f33f013d5f7870";
64680
+ const rawSentryRelease = "boxes-dev-dvb@1.0.1089+448da6d06b2e5e68b5c74e9346f33f013d5f7870";
64681
64681
  const packageVersion = typeof rawPackageVersion === "string" ? rawPackageVersion : void 0;
64682
64682
  const gitSha = typeof rawGitSha === "string" ? rawGitSha : void 0;
64683
64683
  const sentryRelease = typeof rawSentryRelease === "string" ? rawSentryRelease : void 0;
@@ -66894,7 +66894,7 @@ var init_packageVersion = __esm({
66894
66894
  return path8.join(process.cwd(), "dvb");
66895
66895
  };
66896
66896
  readEmbeddedPackageVersion = () => {
66897
- const raw = "1.0.1084";
66897
+ const raw = "1.0.1089";
66898
66898
  return trimVersion(raw);
66899
66899
  };
66900
66900
  readNearestPackageMetadata = (basePath) => {
@@ -80047,4 +80047,4 @@ smol-toml/dist/index.js:
80047
80047
  *)
80048
80048
  */
80049
80049
 
80050
- //# debugId=37a3fca6-6f66-5106-99a6-67552067615c
80050
+ //# debugId=7f4b3604-1af9-5143-b37e-1ae102911c44
@@ -1,17 +1,26 @@
1
1
  # AWS
2
2
 
3
3
  Use this doc when a user asks how to connect AWS, how AWS sign-in stays current,
4
- which accounts or permission sets a project uses, what the `boxes-dev` profile
5
- means, or why a tool or container is not using the managed AWS identity.
4
+ which accounts, permission sets, or access keys a project uses, what the
5
+ `boxes-dev` profile means, or why a tool or container is not using the managed
6
+ AWS identity.
6
7
 
7
- AWS is enabled once for a boxes.dev team, then each team member connects their
8
- own company identity. Each project has a default account and permission set and
9
- can expose additional centrally managed access through named profiles.
8
+ Each project has a default managed profile, `boxes-dev`, and can add named
9
+ managed profiles. Each profile gets its AWS access in one of two ways, and one
10
+ project can mix them:
10
11
 
11
- ## Enable AWS For A Team
12
+ - **Company SSO** uses the company's AWS IAM Identity Center. A team admin
13
+ enables it once for the boxes.dev team, then each member signs in with their
14
+ own company identity and chooses an assigned account and permission set.
15
+ - **Access keys** use a long-term access key that belongs to an IAM user. Any
16
+ member can add one to their own project without team setup, so this works for
17
+ teams that do not use IAM Identity Center.
12
18
 
13
- A team admin opens **Integrations → AWS** in the desktop app and chooses
14
- **Set up AWS**. Enter:
19
+ ## Enable Company SSO For A Team
20
+
21
+ A team admin opens **Integrations → AWS** in the desktop app, chooses
22
+ **Company SSO** next to **Sign in with**, and then chooses **Set up Company
23
+ SSO**. Enter:
15
24
 
16
25
  - the AWS access portal URL the company provides, such as
17
26
  `https://example.awsapps.com/start`; and
@@ -27,15 +36,17 @@ Starting the normal AWS sign-in validates these details before boxes.dev saves
27
36
  them for the team. The admin then finishes company sign-in and chooses an
28
37
  assigned account and permission set for the current project.
29
38
 
30
- Until AWS accepts a team admin's setup request, members see an explanation
31
- instead of a Connect control. They do not need to collect or enter the portal
32
- URL and region themselves.
39
+ Until AWS accepts a team admin's setup request, members who choose Company SSO
40
+ see an explanation instead of a Connect control and can use an access key
41
+ instead. They do not need to collect or enter the portal URL and region
42
+ themselves.
33
43
 
34
- ## Connect AWS
44
+ ## Connect With Company SSO
35
45
 
36
- After a team admin enables AWS, open **Integrations → AWS** in the desktop app.
37
- The team's access portal and region appear as read-only details. Choose
38
- **Connect AWS**.
46
+ After a team admin enables Company SSO, open **Integrations → AWS** in the
47
+ desktop app. **Company SSO** is already selected next to **Sign in with**, and
48
+ the team's access portal and region appear as read-only details. Choose
49
+ **Connect Company SSO**.
39
50
 
40
51
  IAM Identity Center is the AWS sign-in your company uses. boxes.dev opens that
41
52
  sign-in automatically in supported desktop app versions. Finish the normal
@@ -61,23 +72,56 @@ the company's AWS administrator needs to assign that access to the user's
61
72
  identity. After that, choose **Refresh** in the picker to load the new
62
73
  assignment with the existing sign-in; reconnecting is not required.
63
74
 
64
- AWS setup does not change the repository and does not require a Template box
65
- snapshot. New terminals start with `AWS_PROFILE=boxes-dev`. Existing Codex and
66
- Claude sessions keep current work running, then pick up AWS before their next
67
- turn: boxes.dev refreshes their idle runtime after its work drains. This also
68
- applies to Claude sessions opened from mobile. Already-running shells keep the
69
- environment they started with, so open a new terminal after connecting,
70
- changing, or removing AWS.
75
+ ## Use An IAM User's Access Key
76
+
77
+ To give the default profile an access key, open **Integrations → AWS**, choose
78
+ **Access keys** next to **Sign in with**, enter the access key ID and secret
79
+ access key, and choose **Use this key**. Access keys are selected by default
80
+ when the team has not enabled Company SSO. To use a key for a named profile,
81
+ choose **Access keys** in that profile's editor.
82
+
83
+ boxes.dev checks the key with AWS before saving it. It accepts only an active
84
+ long-term key that belongs to an IAM user. It refuses temporary keys, whose IDs
85
+ begin with `ASIA`, keys for the account's root user, and keys AWS does not
86
+ accept, and it explains each case without saving anything. A saved profile
87
+ shows the IAM user's name, the AWS account ID, and the last four characters of
88
+ the access key ID. The secret access key is never shown again.
89
+
90
+ The key belongs to the user who entered it, and boxes.dev uses it only for that
91
+ project and profile. boxes.dev stores it encrypted and does not write it to any
92
+ file on the Template box or devboxes. Each box receives the key from the local
93
+ boxes.dev service when a tool asks for it. The local service and processes that
94
+ received the key keep it in memory, so a sleeping devbox or snapshot taken
95
+ afterward can retain it.
96
+
97
+ Unlike Company SSO credentials, an access key does not expire. AWS tools receive
98
+ the key itself, with no session token or expiration, and anyone who can run
99
+ commands on the project's devboxes, including agents, can read it. Recommend a
100
+ dedicated IAM user whose permissions cover only what the project needs. AWS's
101
+ guide to [managing access keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/access-key-self-managed.html)
102
+ explains how to create one.
103
+
104
+ Access-key profiles do not depend on Company SSO: they keep working when the
105
+ user signs out of Company SSO, and they never need reconnecting.
71
106
 
72
107
  ## How Tools Receive Credentials
73
108
 
109
+ With either method, AWS setup does not change the repository and does not
110
+ require a Template box snapshot. New terminals start with
111
+ `AWS_PROFILE=boxes-dev`. Existing Codex and Claude sessions keep current work
112
+ running, then pick up AWS before their next turn: boxes.dev refreshes their
113
+ idle runtime after its work drains. This also applies to Claude sessions opened
114
+ from mobile. Already-running shells keep the environment they started with, so
115
+ open a new terminal after connecting, changing, or removing AWS.
116
+
74
117
  For a connected project, boxes.dev manages an AWS profile named `boxes-dev` on
75
118
  its real machines. That means the Template box and devboxes in an ordinary
76
119
  project, and the assigned devboxes in a Team Template member project. A project
77
120
  can also have named managed profiles such as `boxes-staging` and
78
- `boxes-production`. Each one selects its own assigned AWS account and permission
79
- set. New terminals and commands in newly started or safely refreshed agent
80
- sessions select the default with the normal AWS environment settings:
121
+ `boxes-production`. Each one uses its own Company SSO account and permission set
122
+ or its own access key. New terminals and commands in newly started or safely
123
+ refreshed agent sessions select the default with the normal AWS environment
124
+ settings:
81
125
 
82
126
  ```text
83
127
  AWS_PROFILE=boxes-dev
@@ -87,10 +131,10 @@ AWS_SDK_LOAD_CONFIG=1
87
131
  Each managed profile uses AWS's `credential_process` feature. In plain terms,
88
132
  when the AWS CLI or a supported software development kit needs credentials, it
89
133
  runs the boxes.dev helper with the exact profile name. The helper asks the
90
- local boxes.dev service, which requests temporary credentials for that
91
- profile's account and permission set. The tool receives the temporary result
92
- in memory; boxes.dev does not write those temporary credentials to the AWS
93
- credentials file.
134
+ local boxes.dev service, which requests temporary credentials for a Company SSO
135
+ profile's account and permission set, or the stored key for an access-key
136
+ profile. The tool receives the result in memory; boxes.dev does not write these
137
+ credentials to the AWS credentials file.
94
138
 
95
139
  Most host-native tools that follow AWS's normal credential provider chain work
96
140
  without repository changes. A quick check is:
@@ -106,20 +150,20 @@ profile explicitly when needed:
106
150
  aws sts get-caller-identity --profile boxes-staging
107
151
  ```
108
152
 
109
- If the renewable AWS sign-in has ended, this command explains that AWS must be
110
- reconnected and includes a boxes.dev link that opens the desktop app's AWS
111
- integration page. The desktop and mobile apps also show an **AWS sign-in
112
- expired.** banner with a **Reconnect AWS** action. Its X dismisses the local
113
- warning without changing the AWS connection, and the warning can return in a
114
- new app session while AWS still needs to be reconnected. On desktop, the action
115
- keeps the current page open and starts the automatic browser flow in supported
116
- app versions. The banner shows progress and provides cancel, retry, and
117
- **Use a code instead** controls when they are needed. On mobile, it shows the
118
- code-confirmation step in boxes.dev; choose **Open AWS sign-in** there to open
119
- the company's AWS access portal in the phone's system browser, where existing
120
- sign-in cookies remain available. Return to boxes.dev after finishing sign-in;
121
- the app checks the same authorization attempt and clears the warning when AWS
122
- reconnects.
153
+ If the renewable Company SSO sign-in has ended, this command explains that AWS
154
+ must be reconnected and includes a boxes.dev link that opens the desktop app's
155
+ AWS integration page. The desktop and mobile apps also show an **AWS Company SSO
156
+ sign-in expired** banner with a **Reconnect AWS** action. Its X dismisses the
157
+ local warning without changing the AWS connection, and the warning can return in
158
+ a new app session while AWS still needs to be reconnected. On desktop, the
159
+ action keeps the current page open and starts the automatic browser flow in
160
+ supported app versions. The banner shows progress and provides cancel, retry,
161
+ and **Use a code instead** controls when they are needed. On mobile, it shows
162
+ the code-confirmation step in boxes.dev; choose **Open AWS sign-in** there to
163
+ open the company's AWS access portal in the phone's system browser, where
164
+ existing sign-in cookies remain available. Return to boxes.dev after finishing
165
+ sign-in; the app checks the same authorization attempt and clears the warning
166
+ when AWS reconnects.
123
167
 
124
168
  The managed profile is a default, not a forced override. An explicit AWS CLI
125
169
  `--profile`, a different `AWS_PROFILE`, access-key environment variables, or a
@@ -128,6 +172,17 @@ For example, `--profile boxes-staging` selects that centrally managed profile,
128
172
  while `--profile dev` selects a separate user-owned `dev` profile if one
129
173
  exists.
130
174
 
175
+ AWS tools also prefer keys in `~/.aws/credentials` over a profile's
176
+ `credential_process`. If that file has a section with the same name as a
177
+ managed profile, such as `[boxes-dev]`, tools will use the keys in that section
178
+ instead of the managed access. boxes.dev does not detect or change that file.
179
+ Rename or remove the section to use the managed profile.
180
+
181
+ Devboxes running an older boxes.dev version receive access-key profiles only
182
+ after they update. Until then, the AWS page shows **Applying AWS access to your
183
+ devboxes**, and if `boxes-dev` uses an access key, those devboxes receive no
184
+ managed profiles at all.
185
+
131
186
  For Codex commands, the managed selection can override an `AWS_PROFILE`
132
187
  assignment in shell startup files such as `.bashrc`. To choose another profile,
133
188
  set it explicitly in Codex's configuration or on the command itself, for
@@ -164,64 +219,86 @@ Identity Center and identity-provider session policies.
164
219
 
165
220
  Temporary account-and-permission-set credentials are requested only when a
166
221
  tool needs them. The local boxes.dev service may keep a still-valid result in
167
- process memory for a short time. Caches are separate for each managed profile
168
- and clear when that profile changes, the project disconnects, or the service
169
- restarts. Each restored devbox must confirm its own current machine identity
170
- before the helper can receive credentials.
222
+ process memory for a short time. An access key has nothing to refresh, so the
223
+ service keeps it in memory until the profile changes. Caches are separate for
224
+ each managed profile and clear when that profile changes, the project
225
+ disconnects, or the service restarts. Each restored devbox must confirm its own
226
+ current machine identity before the helper can receive credentials.
171
227
 
172
228
  ## Change, Remove, Or Reconnect
173
229
 
174
230
  The **Managed profiles** section shows the project's centrally managed access:
175
231
 
176
- - `boxes-dev` is the required default. Use **Edit** to change its account or
177
- permission set.
232
+ - `boxes-dev` is the required default. Use **Edit** to change its account,
233
+ permission set, or access key, or to switch between Company SSO and an access
234
+ key.
178
235
  - Use **Add profile** to create another lowercase `boxes-*` profile, up to 10
179
- total profiles per project. Choose its account and permission set, then
236
+ total profiles per project. Choose Company SSO or an access key for it, then
180
237
  confirm with **Add profile**. The profile name stays fixed after creation so
181
238
  scripts do not silently change identity.
182
239
  - Use a named profile's menu to edit its access or remove only that profile.
183
240
  Removing the default means removing AWS from the project.
184
241
 
242
+ To replace an access key, edit its profile and enter the new key. New AWS CLI
243
+ and SDK processes use the new key once it reaches the box, but a long-running
244
+ process that already loaded the old key keeps using it until it restarts. The
245
+ old key stays active in AWS, so deactivate it there after nothing needs it.
246
+
185
247
  New terminals use a changed default after it reaches their machine. Existing
186
248
  Codex and Claude sessions preserve current work and pick up managed-profile
187
249
  changes before their next turn at the idle boundary described above.
188
- Existing shells and user-managed processes keep their prior environment;
189
- credentials already held in any process can remain usable only until AWS's
190
- expiration time.
191
-
192
- If AWS asks for sign-in again, choose **Reconnect**. The existing managed
193
- profile selections are preserved while the new browser sign-in completes.
250
+ Existing shells and user-managed processes keep their prior environment.
251
+ Temporary Company SSO credentials already held in any process remain usable
252
+ until their AWS expiration, and an access key held in any process remains
253
+ usable until it is deactivated in AWS.
254
+
255
+ If Company SSO asks for sign-in again, choose **Reconnect** or **Reconnect
256
+ Company SSO** in the AWS options menu. Access-key profiles keep working
257
+ meanwhile, and the managed profiles stay editable, so the user can also switch
258
+ an expired Company SSO profile to an access key. The existing managed profile
259
+ selections are preserved while the new browser sign-in completes.
194
260
  Supported desktop app versions open the browser automatically and return to
195
261
  boxes.dev; choose **Use a code instead** if that return is unavailable. On a
196
262
  code-based surface, check that the one-time code shown by AWS matches the code
197
263
  in boxes.dev before continuing. Reconnect uses the team's current portal and
198
264
  region without asking the member to enter them.
199
265
 
200
- Team admins can use **Team setup → Edit** to change the team's access portal or
201
- Identity Center region. Continuing starts a new AWS sign-in for that admin and
202
- updates the team settings only after the new authorization attempt starts
203
- successfully. Existing member connections keep their prior settings until
204
- those members reconnect; an edit does not silently replace an in-use personal
205
- sign-in.
266
+ Team admins can open **Company SSO details** and choose **Edit team setup** to
267
+ change the team's access portal or Identity Center region. Continuing starts a
268
+ new AWS sign-in for that admin and updates the team settings only after the new
269
+ authorization attempt starts successfully. Existing member connections keep
270
+ their prior settings until those members reconnect; an edit does not silently
271
+ replace an in-use personal sign-in.
206
272
 
207
273
  The AWS options menu has two different removal actions:
208
274
 
209
275
  - **Remove from this project** stops future managed AWS credentials for this
210
- project. Other connected projects keep working.
211
- - **Sign out of AWS everywhere** removes the central AWS sign-in from boxes.dev
212
- and disconnects every boxes.dev project using it.
213
-
214
- Neither action changes the user's AWS account assignments, signs the user out
215
- of the company's AWS portal in other browsers, nor revokes temporary
216
- credentials that AWS already issued. Those credentials remain usable only
217
- until their AWS expiration. Use the company's AWS administration and security
276
+ project and deletes boxes.dev's copy of any access keys the project's
277
+ profiles use. Other connected projects keep working.
278
+ - **Sign out of Company SSO** removes the central Company SSO sign-in from
279
+ boxes.dev and disconnects its profiles in every boxes.dev project. Access-key
280
+ profiles stay.
281
+
282
+ If signing out removes a Company SSO `boxes-dev` profile, any named access-key
283
+ profiles in that project remain without a default. New terminals then do not
284
+ set `AWS_PROFILE`, so commands need `--profile` to use those profiles until the
285
+ user chooses default access again. Existing access-key profiles can still be
286
+ edited or removed, but new named profiles need a default first.
287
+
288
+ None of these actions changes the user's AWS account assignments, signs the
289
+ user out of the company's AWS portal in other browsers, or revokes credentials
290
+ AWS tools already received. Temporary Company SSO credentials remain usable
291
+ until their AWS expiration. A removed access key stays active in AWS, and
292
+ processes that already received it can keep using it, until the user
293
+ deactivates it in AWS. Use the company's AWS administration and security
218
294
  controls when immediate AWS-side revocation is required.
219
295
 
220
296
  ## Escalated Admin Access (Advanced)
221
297
 
222
298
  The managed `boxes-dev` profile is the centrally maintained, least-ceremony
223
299
  path for everyday project access. When the same company identity has another
224
- assigned permission set, add a named managed profile and select it explicitly.
300
+ assigned permission set, or another IAM user's key is needed, add a named
301
+ managed profile and select it explicitly.
225
302
  A team can still add a separate user-owned AWS profile on a box, such as an
226
303
  `admin` profile backed by its own `credential_process` command.
227
304
 
@@ -244,5 +321,5 @@ container credential delivery is a separate future integration.
244
321
 
245
322
  The AWS integration supports one IAM Identity Center organization per
246
323
  boxes.dev team, one personal Identity Center sign-in per team member, and up to
247
- 10 centrally managed account/permission-set profiles per project for that
248
- member.
324
+ 10 managed profiles per project for that member. Each access-key profile uses
325
+ one IAM user's key and reaches that user's AWS account.
@@ -587,28 +587,26 @@ Browser can also pop out from the side pane into
587
587
  a near-full-window overlay and dock back into the workbench.
588
588
 
589
589
  The mobile app's Browser shares these tabs and profile. Opening it on a phone
590
- resizes the shared browser to the phone's screen, and with the default
591
- streaming setting the pane keeps showing its last picture. Moving the pointer
592
- into the pane, or focusing it, resizes the browser back to the pane. See
590
+ resizes the shared browser to the phone's screen, and the pane keeps showing
591
+ its last picture. Moving the pointer into the pane, or focusing it, resizes the
592
+ browser back to the pane. See
593
593
  `mobile.md`.
594
594
 
595
- **Account → Advanced → Browser streaming** chooses how the Browser pane
596
- receives the remote page: **JPEG** (the default), **H.264 video**, **WebRTC
597
- via relay**, or **WebRTC direct**, which uses the relay when a direct
598
- connection isn't possible.
599
- The choice is saved to the account, so the mobile app shows the same setting
600
- under **Settings → Advanced**; it affects only the desktop Browser. An open
601
- Browser reconnects with the new choice. When the selected machine hasn't
602
- updated to support the option yet, or a WebRTC option can't get relay access,
603
- Browser keeps JPEG and shows a short notice.
595
+ Browser streams the remote page as WebRTC video on desktop and mobile. It
596
+ connects directly to the box when it can and otherwise through a relay, which
597
+ also works over TCP or TLS on port 443 for networks that block UDP. Switching
598
+ tabs or reopening the pane shows the tab's last picture until video resumes.
599
+ If the stream can't connect after a second attempt, the pane shows
600
+ **Couldn't connect to Browser** with **Try again**. A box whose daemon predates
601
+ WebRTC streaming shows that it needs an update, and a page whose video stops
602
+ shows **Browser stopped updating** with **Try again**.
604
603
 
605
604
  **Account → Advanced → Chrome window** shows the box's whole Chrome window in
606
605
  Browser, with Chrome's own tabs, address bar, menus, and page dialogs in place
607
606
  of the pane's address bar, navigation buttons, and tab strip. It is off by
608
607
  default and saved to the account, and it applies to the desktop and mobile
609
- Browser alike; the mobile app shows it under **Settings → Advanced**. Chrome
610
- window always streams over WebRTC direct, so **Browser streaming** can't be
611
- changed while it's on. Changing the setting restarts the box's browser the next
608
+ Browser alike; the mobile app shows it under **Settings → Advanced**. Changing
609
+ the setting restarts the box's browser the next
612
610
  time Browser connects (an open Browser reconnects right away) and reopens its
613
611
  tabs with sign-ins and profile data intact. The pane keeps **Review page
614
612
  elements**, downloads, pop-out, and a More menu with **Copy page URL**, **Open
@@ -632,6 +630,12 @@ finish opening in the background. If Browser startup or its process stops, the
632
630
  opening view is replaced by an error with a **Restart browser** action;
633
631
  restarting preserves the same profile data.
634
632
 
633
+ An agent on the box can also restart an unavailable Browser and reopen its
634
+ remaining tabs while keeping sign-ins and saved profile data. Reloading tabs
635
+ can lose unsaved form entries. Agents use the shared browser skill's
636
+ `POST /.sprite/api/browser/restart` route; reading the browser's state alone
637
+ does not restart a disconnected browser.
638
+
635
639
  The runtime has no security key or platform authenticator of its own. In the
636
640
  desktop app, Browser-pane passkey forwarding is off by default and can be
637
641
  enabled under **Desktop app settings > Browser > Allow sites to use a passkey
@@ -38,12 +38,61 @@ snapshot and then create the devbox.
38
38
  If an ordinary project's Template box has changed in a way future devboxes should inherit, take a
39
39
  new snapshot before starting the devbox.
40
40
 
41
+ ### Choose starting branches
42
+
43
+ In a new desktop draft, the **Branch** menu below the composer selects the branch
44
+ to prepare before Codex or Claude starts. Choose a branch from the list or enter its name. A
45
+ multi-repository project has a separate choice for each repository; the agent's
46
+ working directory is independent of those choices. Branch names other than
47
+ `main` or `master` are shown in blue in the closed menu so a remembered choice
48
+ stays visible. Menu options use neutral text, with an inline **Project default**
49
+ badge for the configured default. Search filters cached remote branch names from
50
+ the prepared devbox; it does not query the remote as the user types. Unlisted
51
+ names can still be entered and are verified when fetched.
52
+
53
+ boxes.dev fetches the selected remote branches and checks them out before
54
+ running startup scripts. It remembers choices on this computer for the signed-in
55
+ account after the first message is accepted. Discarding a draft does not change
56
+ that preference. Clients without this picker use the project's configured
57
+ defaults.
58
+
59
+ Setup and import show default branches and startup commands as separate settings
60
+ under **New devboxes**. Project settings show configured defaults above the
61
+ startup script. Existing projects without managed defaults can keep the branch
62
+ saved in the Template box snapshot by choosing **From Template box**.
63
+
64
+ Projects using the generated Git startup commands retain their existing reset
65
+ and clean behavior on the new devbox: tracked files match the fetched branch,
66
+ untracked files are removed, and ignored files such as dependencies remain.
67
+ Existing projects without those generated commands keep their saved checkout
68
+ until a branch is explicitly selected. An explicit choice in such a project
69
+ preserves local work and stops for conflicting changes or unpublished commits.
70
+ The Template box is unaffected.
71
+
72
+ Changing a choice while composing prepares the latest selection. Before setup
73
+ has run, boxes.dev can reuse the same devbox; after setup starts, it prepares a
74
+ replacement so setup runs against the chosen code. **Send** waits for the
75
+ selected branches. A missing branch or checkout conflict keeps the draft
76
+ available to correct or retry. Once the thread starts, its branch picker no
77
+ longer changes the checkout. Threads on existing devboxes and copies of an
78
+ existing conversation keep that devbox's code.
79
+
80
+ ### Startup after checkout
81
+
41
82
  To configure startup behavior, open **Project settings** in the desktop app and
42
83
  edit **Startup script** under **Devbox lifecycle** > **New devbox defaults**.
43
84
  The field saves shell commands directly as a project setting; boxes.dev does
44
85
  not create a script file for it. The startup timeout defaults to 60 seconds and
45
86
  can be set from 1 to 120 seconds.
46
87
 
88
+ Startup scripts can install dependencies, configure the environment, or start
89
+ services after branch preparation. The standard generated fetch/checkout
90
+ commands are handled by boxes.dev; any extra commands remain startup work.
91
+ Remove branch-switching commands from custom scripts when choosing starting branches.
92
+ If setup leaves a repository on another branch, boxes.dev reports the conflict
93
+ before starting the agent. A successful checkout alone does not mean an app
94
+ is listening or has rebuilt for that branch.
95
+
47
96
  When a project has a devbox startup script, boxes.dev may reserve a
48
97
  disposable devbox and run that script after the user starts typing, before the
49
98
  first prompt is sent. For Codex and Claude Code, boxes.dev may also prepare the conversation
@@ -76,6 +125,12 @@ shows a warning for that result. Dismissing the warning acknowledges that exact
76
125
  result across desktop, mobile, and reloads; a different startup failure can
77
126
  still show its own warning.
78
127
 
128
+ When choosing starting branches, checkout must finish and setup must leave the selected
129
+ branches checked out before the agent starts. A script that changes branches
130
+ needs to be corrected before retrying preparation. If boxes.dev cannot confirm
131
+ that a timed-out command stopped, it retains the draft for retry instead of
132
+ starting the agent while that command may still be changing files.
133
+
79
134
  ## Agent Guidance For New Devboxes
80
135
 
81
136
  The project's **New devbox defaults** settings can include shared agent guidance
@@ -136,5 +136,5 @@ load once wake finishes.
136
136
 
137
137
  ## Work Product URL
138
138
 
139
- A URL attached by a Linear-triggered agent to the current Linear Agent Session
140
- as a result or artifact of the work.
139
+ A URL attached by an agent to a Linear Agent Session as a result or artifact
140
+ of the work. An ordinary thread can select the destination explicitly.
@@ -100,9 +100,9 @@ Use this terminology consistently:
100
100
  - `remote-assistants.md`: connecting an outside assistant to selected projects,
101
101
  finding and continuing threads, progress and events, cancellation boundaries,
102
102
  and removing access.
103
- - `aws.md`: central AWS IAM Identity Center sign-in, per-project account and
104
- role selection, the managed `boxes-dev` profile, credential precedence,
105
- refresh behavior, removal, and container limits.
103
+ - `aws.md`: central AWS IAM Identity Center sign-in, IAM user access keys,
104
+ per-project account and role selection, the managed `boxes-dev` profile,
105
+ credential precedence, refresh behavior, removal, and container limits.
106
106
  - `google-cloud.md`: central Google sign-in, per-project Google Cloud project
107
107
  selection, how `gcloud` and client libraries receive credentials, credential
108
108
  precedence, reconnecting, removal, and container limits.
@@ -130,8 +130,26 @@ or other work products:
130
130
  boxes-linear attach-url "https://example.com/artifact" --label "Pull request"
131
131
  ```
132
132
 
133
- The URL appears in Linear as a work product for the session. This write-back is
134
- available only inside Linear-triggered boxes.dev automation runs.
133
+ The URL appears in Linear as a work product for the session. From an ordinary
134
+ boxes.dev thread, list your available sessions and select the intended one:
135
+
136
+ ```bash
137
+ boxes-linear sessions --json
138
+ boxes-linear attach-url "https://example.com/artifact" --label "Report" --session-id "<agent-session-id>"
139
+ ```
140
+
141
+ Discovery checks your 100 most recent sessions in your team's connected Linear
142
+ workspace. Only sessions owned by your currently linked Linear account are
143
+ available, including sessions blocked before an automation started. Failed,
144
+ stopped, and canceled sessions cannot receive work products through this tool.
145
+ Use the Agent Session id from discovery, not an issue id or URL. If the intended
146
+ session is unclear, ask the user to choose. If no session exists, start one with
147
+ the boxes.dev agent in Linear.
148
+
149
+ Selecting a session applies only to that attachment. It does not redirect
150
+ Linear replies or progress to the calling thread, and does not start an
151
+ automation. Without `--session-id`, the command uses the current automation's
152
+ session.
135
153
 
136
154
  ## Troubleshooting
137
155
 
@@ -158,5 +176,7 @@ latest Template box snapshot for an ordinary project, or the current saved
158
176
  Team Template version for a member project. If several assignments start at
159
177
  once and some do not launch, check awake devbox capacity and billing.
160
178
 
161
- If work products do not attach, confirm the agent is running inside a
162
- Linear-triggered automation and that the URL is valid.
179
+ If work products do not attach, check the URL and the selected session. In an
180
+ ordinary thread, run `boxes-linear sessions` and pass `--session-id`. If the
181
+ commands are missing on an older box, let its boxes.dev service update before
182
+ retrying.
@@ -31,6 +31,11 @@ that protection sooner. When the limit expires, normal idle sleep can resume;
31
31
  the limit does not terminate the command. You can still sleep the machine
32
32
  yourself.
33
33
 
34
+ A boxes.dev update can restart Claude, which stops its running background
35
+ commands. boxes.dev will then send the agent a message in the thread that lists
36
+ the stopped commands, so it can check their work and restart any it still
37
+ needs.
38
+
34
39
  ### Scheduled checks and keep-awake requests
35
40
 
36
41
  An agent can save one later check in its current thread, from one minute to
@@ -183,13 +188,14 @@ own switch and remain available independently.
183
188
 
184
189
  To keep watching an app while you work in other threads, select its devbox,
185
190
  open **Ports**, and choose the computer icon beside the **Port forwarding** switch, labeled
186
- **Keep localhost on this devbox**. The icon will turn amber and gain a dot.
191
+ **Pin localhost to this devbox**. The icon will turn amber.
187
192
  All of that devbox's eligible ports, including newly detected ports, will stay
188
193
  on localhost when you select another thread, project, or new-thread draft.
189
194
  The choice is saved for your account on this computer and survives desktop app
190
195
  restarts. It can also target a Template box.
191
- The devbox's right-click menu and the Template box's actions menu offer the
192
- same keep and release actions.
196
+ To release localhost without opening the box, choose **Unpin localhost** from
197
+ that devbox's right-click menu or the Template box's actions menu. This action
198
+ appears only on the box keeping localhost.
193
199
 
194
200
  An amber computer icon in the sidebar marks the chosen box. On another devbox,
195
201
  the Ports menu still shows that devbox's ports, with an amber
@@ -290,9 +296,8 @@ either surface appears in the other, and either surface can stop sharing it.
290
296
  Anyone with a public link can reach the app without signing in. Stop sharing
291
297
  temporary links when they are no longer needed; stopping the app alone leaves
292
298
  the link allocated and visible, although requests are unavailable until the app
293
- returns. After the app returns, the public link can continue showing the
294
- unavailable page for up to one minute while its availability refreshes; retry
295
- the link after that interval.
299
+ returns. After restarting the app, allow a few seconds for detection and link
300
+ availability to refresh, then retry the link.
296
301
 
297
302
  ### Project forwarding rules
298
303
 
@@ -473,9 +473,10 @@ If the new account is out of usage too, a turn that hits its limit waits up to
473
473
  a minute and continues on the next account rotation selects. A Codex turn that
474
474
  stopped at a usage limit before the switch still needs a follow-up. When Claude hits a usage limit and automatic selection finds another
475
475
  account, boxes.dev resumes the same conversation and continues the unfinished
476
- request before queued follow-ups. Stop cancels this recovery. With no available
477
- account, or with background work or pending steering that cannot be safely
478
- resumed, the turn stays stopped.
476
+ request before queued follow-ups. Switching accounts restarts Claude, stopping
477
+ its background commands and agents. Claude checks completed work before
478
+ recovering unfinished work. Stop cancels this recovery. With no available account,
479
+ or pending steering that cannot be safely resumed, the turn stays stopped.
479
480
 
480
481
  Configure agents manages the Codex and Claude accounts that run coding-agent
481
482
  threads. Remote MCP connections are managed separately from **Integrations →
@@ -512,12 +513,13 @@ setups remain **Template-managed**. Configure those on the Template box and take
512
513
  a snapshot when future devboxes need to inherit that local machine state.
513
514
 
514
515
  Company AWS access is managed separately from project setup under
515
- **Integrations → AWS**. The user completes the company's normal AWS sign-in and
516
- chooses one assigned account and role for the project. boxes.dev then applies
517
- the managed `boxes-dev` profile to the Template box and devboxes without
518
- changing the repository or requiring a new snapshot. Open a new terminal or
519
- agent session after connecting or changing the role. See `aws.md` for profile
520
- precedence, central refresh, removal, and container limits.
516
+ **Integrations → AWS**. The user either completes the company's normal AWS
517
+ sign-in and chooses one assigned account and role for the project, or enters an
518
+ IAM user's access key. boxes.dev then applies the managed `boxes-dev` profile to
519
+ the Template box and devboxes without changing the repository or requiring a
520
+ new snapshot. Open a new terminal or agent session after connecting or changing
521
+ the role. See `aws.md` for profile precedence, central refresh, removal, and
522
+ container limits.
521
523
 
522
524
  Project setup Codex scans may use the user's local Codex sign-in on this
523
525
  computer or the boxes.dev Codex proxy, depending on which setup path is
@@ -213,11 +213,19 @@ requesting tool's process memory, but boxes.dev does not write them to the AWS
213
213
  credentials file. A role change or disconnect clears the managed local cache;
214
214
  credentials AWS already issued can continue only until their AWS expiration.
215
215
 
216
+ A profile can instead use an IAM user's long-term access key. boxes.dev stores
217
+ the key encrypted for the user's project and profile and does not write it to
218
+ files on the box. The helper gives the key itself to requesting tools, so any
219
+ process or person that can run commands on the project's machines can read it,
220
+ and the local service, those processes, and later memory snapshots can retain
221
+ it. It stays valid until the user deactivates it in AWS.
222
+
216
223
  Removing AWS from one project stops future managed credentials for that
217
- project. Signing out of AWS everywhere removes the encrypted central sign-in
218
- and disconnects all of the user's boxes.dev projects. Neither action changes
219
- AWS account assignments, signs out other AWS portal browser sessions, or
220
- performs immediate AWS-side revocation. Use the organization's AWS controls
224
+ project and deletes boxes.dev's copy of its access keys. Signing out of Company
225
+ SSO removes the encrypted central sign-in and disconnects its profiles in all
226
+ of the user's boxes.dev projects; access-key profiles stay. Neither action
227
+ changes AWS account assignments, signs out other AWS portal browser sessions,
228
+ deactivates access keys, or performs immediate AWS-side revocation. Use the organization's AWS controls
221
229
  when that is required. See `aws.md` for setup, profile precedence, and current
222
230
  container limits.
223
231
 
@@ -366,8 +366,11 @@ either rename the Team Template MCP to keep both or skip that inherited MCP.
366
366
  Account-wide MCPs apply across all projects and are edited from ordinary MCP
367
367
  settings.
368
368
 
369
- The **Integrations** editor supports AWS, Tailscale, Slack, and Linear. The
370
- team connection must be usable before an admin first adds a provider. Marking
369
+ The **Integrations** editor supports AWS, Tailscale, Slack, and Linear. For
370
+ Tailscale, Slack, and Linear, the team connection must be usable before an
371
+ admin first adds the provider. AWS needs no team connection, because members
372
+ can use their own IAM user access keys when the team has not set up Company
373
+ SSO. Marking
371
374
  one **Required** holds the project owner's initial Finish action until their
372
375
  personal or project connection is ready. Marking one **Recommended** lets the
373
376
  owner choose **Finish without recommendations**. The saved requirement contains
@@ -691,11 +691,12 @@ available to Codex on that machine. Each row shows where the skill comes from:
691
691
  Project, Personal, Plugin, Account (a plugin installed through your ChatGPT
692
692
  account or workspace), Admin, or Built-in. Choosing a skill inserts a `$name`
693
693
  link to its `SKILL.md`, and Codex will load that skill's instructions with the
694
- message. A new thread on mobile, or a desktop **New devbox + thread** draft,
694
+ message. Before the box connects, including in a new thread, the composer
695
695
  shows the skills boxes.dev last read from a Codex thread in the same project,
696
696
  so its list fills in once a started Codex thread in that project has been
697
697
  opened; Account skills appear there only while the Codex account they came from
698
- is selected. A machine with an older boxes.dev service won't show the list
698
+ is selected. Once connected, the list comes from that box. A machine with an
699
+ older boxes.dev service won't show a live list
699
700
  until its normal automatic update runs.
700
701
 
701
702
  Codex also shows context-window usage when available. When the context window
@@ -787,7 +788,7 @@ supports slash commands when the thread surface has command lookup
787
788
  enabled. Type `/` in a Claude reply box on desktop or mobile to list Claude's
788
789
  commands and skills; choosing one adds it to the message. Skill rows show
789
790
  Project, Personal, Plugin, or Account (skills synced from the claude.ai
790
- account). A new thread on mobile, or a desktop **New devbox + thread** draft,
791
+ account). Before the box's live list is ready, including in a new thread, the composer
791
792
  uses the project's most recently opened Claude thread for project and personal
792
793
  skills, and the selected Claude account's last list for its synced skills and
793
794
  Claude's built-in commands, which depend on the account's plan. On mobile, the
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@boxes-dev/dvb-runtime",
3
- "version": "1.0.1084",
3
+ "version": "1.0.1089",
4
4
  "description": "Runtime for the boxes.dev CLI. Install @boxes-dev/dvb to use the CLI.",
5
5
  "homepage": "https://boxes.dev",
6
6
  "type": "module",
@@ -77,5 +77,5 @@
77
77
  "e2b": "^2.18.0",
78
78
  "ink-testing-library": "^4.0.0"
79
79
  },
80
- "devboxReleasedAt": "2026-10-17T04:57:56Z"
80
+ "devboxReleasedAt": "2026-10-17T20:33:19Z"
81
81
  }