Siri Shortcuts and App Intents
Open saved hosts and run pinned commands from Siri, Shortcuts, and automations.
Overview
vmux exposes two App Intents to the rest of the system. App Intents are how iOS, iPadOS, and visionOS apps offer their actions to Siri, the Shortcuts app, Spotlight, Focus filters, and home-screen automations. With the intents below you can open a saved server with one phrase, or paste a stored command into the active terminal from a single tap on a Shortcut tile.
| Intent | What it does | Title in Shortcuts |
|---|---|---|
| Connect to Server | Opens a new terminal connected to a saved host. | Connect to Server |
| Run Clip | Sends a saved command (a "clip") to the currently active terminal pane. | Run Clip |
Both intents run in the vmux process. They bring the app to the foreground if it is not already there, then dispatch the action via an internal URL handler. Nothing is sent to a server until you confirm the action inside vmux.
Connect to Server
Opens a new terminal window and starts a connection to a host you have already added to vmux.
Parameters
| Parameter | Type | Source |
|---|---|---|
| Server | A saved host | The list comes from your Saved Hosts, the same list shown in the Workspace Panel. |
The Server picker shows each host's label (or username@host if no label is set) and its connection target as a subtitle. Hosts you have not saved are not selectable from Shortcuts.
How to invoke it
- Siri — say "Connect to Server in vmux" or "Open Server in vmux", replacing Server with the saved host's label. Both phrases are pre-registered, so they work without any Shortcuts setup.
- Shortcuts app — add a "Connect to Server" action and pick a saved host. Run it from the Shortcuts app, share sheet, home screen tile, or Apple Watch face.
- Automations — wire it into a personal automation (NFC tag, time of day, focus mode, location) and Shortcuts will resolve and run it without prompting.
- Spotlight — type the host's name. The intent surfaces with a "Connect" button.
Example use cases
- Morning standup — a NFC tag at your desk runs "Connect to prod-bastion" so the right window is open before you sit down.
- Focus mode — a "Work" focus automation that opens vmux to your dev box every weekday at 9am.
- Apple Watch tile — bind your most-used host to a complication for a one-tap connect.
Run Clip
Sends a stored command to the active terminal pane. A "clip" in vmux is a pinned command — see Saved Hosts for how to pin one. Clips are useful for routine commands you do not want to retype: deploys, log tails, restarts, status checks.
Parameters
| Parameter | Type | Source |
|---|---|---|
| Clip | A pinned command | The list comes from your Pinned Commands in the Workspace Panel. |
The Clip picker shows the command text directly, since clips do not have separate labels.
How to invoke it
- Shortcuts app — add a "Run Clip" action, pick a clip, and assign the shortcut to a tile or automation.
- Siri — once the shortcut exists in the Shortcuts app you can name it ("Hey Siri, deploy production") and Siri will run it.
- Stack with other actions — Shortcuts lets you chain actions. Combine Connect to Server with Run Clip to "open the box and immediately run a status check".
Behavior
Run Clip targets the currently active terminal pane in vmux. It does not pick a pane for you. If no terminal is focused, vmux opens to the most recently active window first, and the clip runs there. The command is sent as plain text — the same as if you had typed it. If your shell has a confirmation prompt for destructive commands, that prompt still fires.
Build a Shortcut: One-tap Connect to a Host
Let's wire a host called prod-bastion to a tile on your iPhone home screen.
- Open the Shortcuts app on your iPhone (or visionOS).
- Tap + in the top right to start a new shortcut.
- Tap Add Action, search for "vmux", and pick Connect to Server.
- Tap the Server field. Pick prod-bastion from the list of saved hosts.
- Tap the shortcut name at the top and rename it to something short — "Connect Prod" works.
- Tap Done.
- Long-press the shortcut card on the Shortcuts grid and pick Add to Home Screen. Choose an icon and a label.
You now have a tile that opens vmux straight into a connection to prod-bastion. You can use the same flow on visionOS — pin the shortcut to your home view, or trigger it from a glance on Apple Watch if you have the Shortcuts complication.
To go further, edit the shortcut and add a Run Clip action after Connect to Server. Pick a clip such as kubectl get pods -A. Now the same tile connects and runs your status command in one tap.
Tips and Limits
- First run prompts. The first time an intent runs, iOS asks you to allow vmux to be invoked from Shortcuts. Approve once and it remembers your choice.
- App must be installable on the source device. Run Clip dispatched from your iPhone runs in iPhone vmux. Run Clip from your Vision Pro runs in visionOS vmux. Intents do not cross devices.
- Saved hosts and clips must already exist. Intents read from your existing settings — they do not create or edit hosts. Add hosts and pin commands from the Workspace Panel first.
- Authentication still applies. Connect to Server uses whatever authentication is configured on the host (password, Secure Enclave, agent, or iPhone signer). If a host needs Face ID or a biometric prompt, you will see it after the intent fires.
- Errors stay quiet. If an intent's target host has been deleted, the intent silently no-ops. Check that the saved host or clip still exists.
Related
- Saved Hosts — adding and pinning hosts
- Authentication Methods — what each connection requires
- Command Palette — the in-app equivalent of these intents