Skip to main content
On a Mac, the boxd CLI puts your machines in the menu bar. Click the boxd icon to see every machine in your active organization with its status, create a new one, open a shell on it in your terminal, open its website, and pause, hibernate or stop it. It uses the CLI’s login, so there is nothing to set up.

New machine, Connect in Ghostty, start nginx, open the machine's URL, then Hibernate.

​
Turn it on

The menu bar is part of the CLI, so there is no separate download. Install the CLI and sign in:
The CLI’s background daemon then shows the boxd icon in your menu bar. It is on by default and needs macOS 13 or later, like the macOS CLI. The first time you open it, it says what it can do. Get started takes you to your machines. To hide it, use the red button in its footer, or:
Hiding it leaves the daemon running, so ~/.ssh/config sync and the client utilities keep working.

​
Your machines

The list shows the machines in your active organization: a status dot, the name, the size and the status. When your organization uses more than one region, every region’s machines are listed, each tagged with its region. Filter machines narrows the list as you type. The header shows:
  • The organization. Click it to switch. The boxd CLI switches with it, the same as boxd auth switch.
  • How many machines are running, and your credit balance. The balance opens billing in the console.
  • Refresh. The list also updates on its own while it is open.
The icon itself shows how many machines are running. Turn the number off in Settings with Show how many machines are running.

​
Connect, open, and everything else

Hover a machine for its one-click actions:
  • Connect (the terminal icon) opens boxd machine connect in your terminal. See Choose your terminal.
  • Open (the compass) opens the machine’s public URL, https://<machine>.boxd.sh, in your browser.
  • A machine that is asleep or stopped shows the control that brings it back: Resume on standby, Wake when hibernated, Start when stopped. A machine on standby keeps Connect and Open too, since a connection wakes it.
The ⋯ menu, also on right-click, has everything that applies to the machine’s state: Anything that interrupts a machine asks first, at the top of the menu. Hibernate myapp? says what happens, Its memory is written to disk and the host is released, and waits for Hibernate or Cancel. Remove deletes the machine and its disk for good; snapshots you captured from it are kept.

​
Create a machine

New machine, at the bottom of the menu, is the console’s New machine dialog:
  • Name. Optional: boxd picks one.
  • Region. When your organization uses more than one. The machine stays in that region.
  • Start from. When your organization has a snapshot to start from. A machine restored from a snapshot keeps the snapshot’s size.
  • Size. Your organization’s default, or 1 vCPU and 4 GiB, 2 vCPU and 8 GiB, or 4 vCPU and 16 GiB.
  • Isolated. A sandbox that is reachable only through networks you add later. This can’t be changed after creation.
Create machine runs boxd machine new in the active organization, and the new machine shows up in the list as it starts.

​
Choose your terminal

Connect opens a shell in the first of these that is installed, or the one you pick in Settings under Open shells in: The first time you connect, macOS asks whether boxd may control that terminal. If you said no, allow it in System Settings → Privacy & Security → Automation, then connect again.

​
Settings

Open Settings from the gear in the menu’s footer:
  • Connect. Your terminal, as above.
  • Account. Who is signed in, the organization, and Sign Out. Signing out here signs the CLI out on this Mac too.
  • Menu bar. Show or hide the number of running machines, and Hide from Menu Bar.
  • About. The CLI it runs from, its version, and Show the welcome again.

​
Troubleshooting

No icon after you installed the CLI. Sign in with boxd auth login, then check that boxd config get menubar.enable says true. The icon is hidden behind the notch. On a MacBook with a notch, macOS hides menu bar icons that don’t fit next to it, and doesn’t say so. Quit or hide another menu bar app until the boxd icon shows, then hold ⌘ and drag it to the right, next to the clock. macOS remembers where you put it. A menu bar manager such as Ice can also show icons that don’t fit. Connect says boxd isn’t allowed to control your terminal. Allow it in System Settings → Privacy & Security → Automation.