The Vectis app
What each part of the Mac app does, and where to find the CLI and MCP equivalents.
The app is a window onto the background service. Closing it leaves the service and its jobs running. Everything in the app is also available in the vectis CLI and to agents through vectis-mcp.
| View | What it shows and does | CLI |
|---|---|---|
| Overview | The service, recent VMs, what needs you and the latest activity. Pause or resume new VMs, stop or reconcile VMs. The menu stops the service when idle or removes the login service. | status, pause, resume |
| Activity | Everything this Mac was asked to do, grouped by day or repository, with search and filters. Open one to see its steps, dismiss it, or stop the work it owns. | activity, operation |
| Environments | Your guest images. Prepare Ubuntu, macOS or Windows, register an existing image, start a clean VM, and set default CPU, memory and VM folder. | environment |
| Repositories | Your repositories, each with the environments it runs on, their runs-on label, the Automatic switch, Start runner, recent jobs, workflow migration and disconnecting. |
repository, runner, job, migration |
| Connections | Connect this Mac to your account, link GitHub, and sign in to control your other Macs. | cloud, github, login |
| Storage | Disk usage of images and VMs, including blocks shared between copies. | storage |
| Diagnostics | Host support, runtime components, the service log and the command line tools installer. | doctor, logs |
| Settings | How many VMs this Mac runs at once, and whether it takes on new VMs. | machine configure, pause, resume |
Keyboard: Cmd+1 to Cmd+7 switch views, Cmd+, opens Settings, Cmd+B toggles the sidebar.
Activities and their steps
An activity is one thing you or GitHub asked for: preparing an environment, running a job, connecting a repository. The operations underneath it are the steps that carried it out, and you see them as Steps when you open an activity. Preparing macOS, for example, is one activity whose steps are the installation, the setup console, the guest SSH enrollment and its verification.
An activity’s status is the status of the work Vectis did. For a job, the GitHub result is a separate badge: a runner can finish cleanly while the job it ran fails, and both facts are shown.
What the app tells you
Every view follows the service by itself: a change you make anywhere, and a change GitHub reports, appear without refreshing or switching views.
A setting that applies immediately, such as the Automatic switch, is confirmed by a notification once the service has applied it. Work that takes longer, such as preparing an image or running a job, is confirmed as started and then continues in Activity. Notifications about something that worked disappear on their own; a failure, or anything waiting for you, stays until you dismiss it.
While the app runs, native macOS notifications report new local activities that need you or fail, even when the window is hidden or minimized or another Mac is selected. They are suppressed while focused; clicking opens the local activity. Startup history is not replayed. Closing the last window stops notifications. The desktop-local Notify me when Vectis needs me or work fails preference defaults on; its Settings toggle will be added separately.
Control another Mac
After signing in under Connections > Other Macs, the machine switcher at the bottom of the sidebar selects which Mac the views control. File pickers work only for this Mac; for another Mac, type paths that exist on it. Service installation and pairing only work on the Mac itself. See Remote control.
Updates
The app updates itself from GitHub Releases and restarts the service only when it is idle. See Updates.
Machine resource settings
Settings controls the concurrent runner limit (1 to 16, default 5). The shared VM memory budget is also configurable through vectis machine configure --memory-budget-mib <N>, independently or alongside --max-runners <N>. It defaults to 75 percent of host RAM and accepts 2048 MiB to total host RAM. Lowering it gates future starts without stopping current VMs.
Environment CPU and memory values are per-VM ceilings. CPU overcommit is allowed; memory admission uses measured VM usage with startup floors, and warning or critical host memory pressure blocks new VMs. vectis status --json exposes runnerCapacity.budget for the effective budget, committed memory, host RAM and pressure, plus pressureKnown to distinguish unknown pressure. See VM storage and resources for accounting and recommended ceilings.