Computer access

Agents work on devboxes in the cloud, but a task sometimes needs something that exists only on your own computer: a file in your Downloads folder, an app or tool you have installed, or the state of your local checkout. Computer access lets an agent ask the boxes.dev desktop app on your Mac to run a command there or copy a file or folder to its devbox. Nothing runs or copies until you approve it, unless you choose to always allow it.

Computer access works with the desktop app on macOS. It's rolling out to teams gradually, so if the desktop app's Settings has no Computer access section, it isn't available for your team yet.

Turn on computer access

1. In the desktop app, open Settings → Computer access.
2. Under Agent requests, select Turn on….
3. Check the account and computer name in the confirmation, then select Turn on.

Settings will show On for your email address. Computer access works on one computer at a time, so turning it on on another Mac moves it there.

Agents can only ask when their devbox or project allows it, and it's off until you choose otherwise. Open the project's settings, expand Agent permissions for this project, and set Computer access to Ask each time. Devboxes that follow the project will use that setting, and a devbox can have its own in its Agent permissions. An agent that needs computer access can also ask for it in its thread, and you can allow or deny that request there.

Team admins decide whether members can use computer access under Computer access in the team's settings. Allowed lets each member choose for their own devboxes and projects. Ask every time means every request will need approval, so members can't allow a devbox or project for longer. Off stops agents on the team from asking.

Approve a request

When an agent asks while you're using the desktop app, a card will appear in the top-right corner of its window, asking whether to run the command or copy the file, with the agent's reason. If you're in another app, you'll get a notification, the Dock icon will bounce, and the card will appear when you switch to boxes.dev.

• Allow runs the command or makes the copy, this time only.
• Allow for 3 hours runs it, and for the next 3 hours lets agents on the same devbox run commands and copy files without asking. Other devboxes keep asking.
• Deny refuses the request, and the agent will be told.

Select Details to see the rest before you decide: the thread that sent the request, the folder and timeout, and the devbox and project it came from. From there you can also turn off requests from that devbox, or always allow it. Nothing on the card changes the project's setting. The thread's own transcript shows the request too, with Deny.

A command runs as you, in your login shell, with your files, your network, your SSH keys, and any apps or tools you're signed in to. Read each command before you approve it. Anything an agent reads, such as a web page or an issue, could lead it to ask for something you don't want.

A request waits up to 10 minutes for your answer. Once approved, a command runs for up to its timeout, which is at most 10 minutes. If the desktop app quits while a command is running, it stops the command, and the agent will be told that the command may have run only partly.

Always allow a devbox or project

To stop the prompts from one devbox you trust, select Details on one of its requests, then Always allow this devbox…, and confirm. Its commands and copies will run without asking, including while your Mac is locked. Other devboxes in the project will keep asking.

To always allow every devbox in a project, set Computer access to Always allow in the project's Agent permissions. You can do the same for one devbox in its own Agent permissions. The first request after you choose it shows Confirm on this computer…, and requests will run without asking once you confirm. While a 3-hour allowance from the card lasts, the setting shows Allow all until its end time, and afterward agents ask each time again.

Settings lists the devboxes and projects that run without asking under Always allow, each with Remove. Recent activity shows recent requests from all your devices.

Copy files to a devbox

When you approve a copy, the file or folder will be saved on the devbox in a new folder under ~/computer-files/, or where the agent asked for it, and the devbox's agents will be able to read it. A copy can hold up to 100 MB and 10,000 files. Files stored only in iCloud are downloaded first.

boxes.dev doesn't copy from keychains, browser profiles, or the desktop app's own data, and the card warns you before copying folders such as ~/.ssh that can hold keys or passwords. On a Template box, devboxes made from its next snapshot will have the copy too.

Approve requests from your phone

While your Mac is locked, it can't show a card, so agents are told you're away. To approve those requests on your phone instead, pair it with your Mac:

1. In the boxes.dev mobile app, open Settings → Computer access → Phone approval and confirm with Face ID, Touch ID, or your passcode.
2. Your Mac will show a window with your phone's name and a 4-digit code. Check that it matches the code on your phone, then select Allow.

Requests that need approval while your Mac is locked will then come to your phone, and you can approve them with Face ID, Touch ID, or your passcode. Only the paired phone can approve. Pairing another phone replaces it, and signing out of boxes.dev on the phone ends the pairing. To stop, select Turn off phone approval on the phone, or Turn off next to Phone approval in the desktop app's Settings.

Phone approval needs a recent version of the boxes.dev mobile app. If its Settings has no Computer access section, update the app.

Pause or turn off computer access

Select Pause in Settings → Computer access to stop requests for a while. Agents will be told that you paused computer access, and your Always allow settings stay. Select Resume to receive requests again.

Turn off stops requests and erases this computer's Always allow confirmations and phone pairing. When either is saved, Settings asks you to confirm and suggests Pause instead.

Limits

• Threads started by automations, and the project coordinator, can't use computer access.
• At most five requests can wait for approval at once.
• A command's output is limited to 5 MB.