Scripts

A script is a shell or PowerShell script that you write and run on your Mac or in a VM. It can be triggered from anywhere with its hook. This turns your Mac into a CI/CD server, with your own setup and data.

Ask your AI agent

The easiest way to write and run a script is to ask your coding agent. It writes the script and saves it in VMPal's Hub. It runs the script where you say, and reads the log when a run fails. It uses VMPal's MCP tools for this, or vmpal script in its terminal.

In VMPal, open Settings › AI Agents and turn on Let coding agents on this Mac manage all VMs.
Click Add to Claude Code, or another agent's button (which ones), and restart the agent.
Ask it, for example:
- "Write a VMPal script that builds this app in my Windows VM and run it now."
- "Run my test script and tell me why it failed."
- "Make my build script run in a fresh clone of my Ubuntu VM, and stop it after 30 minutes."

The rest of this page explains how scripts work, for when you want to know.

Make one

VMPal keeps your scripts in its Hub.

Open the Hub. Click Hub in the toolbar of VMPal's window, or choose View › Hub (⌘2).
Click New Script. Name it, choose its language, write it, and click Create. A new script starts with a comment that lists its variables.
Choose where it runs. Click Choose… beside Runs On in the sidebar. Or open the script's menu (right-click the script, or click ⋯) and choose Change Where It Runs….

Where it runs

A script can run in a fresh clone of a VM, in the VM itself, or on your Mac. Choose more than one, and it runs in each.

Runs in a VM need agent control. So VMPal turns it on in each VM a script runs in.

A fresh clone of a VM

This is the default for a VM. A clone is a throwaway copy of the VM, like a fresh CI runner. Each run gets its own clone, and VMPal deletes it after the run.

It's light. VMPal makes the clone at once. Light clones need APFS. For a VM on a drive that isn't APFS, runs use the VM itself.
The VM must be shut down. Use the VM's Shut Down. Closing its window saves the VM instead of shutting it down.
A run waits up to 30 minutes for the VM to shut down. After that, VMPal skips the run.
The clone has nothing from your Mac. It gets no shared folders, forwarded ports or clipboard.

The VM itself

To run in the VM itself, uncheck Clone a new VM each run under the VM when you choose where the script runs. The sidebar then shows Runs in the VM itself under the VM.

VMPal starts or resumes the VM in the background. It signs in at the sign-in screen with the password VMPal keeps. It leaves the VM running after the run.
If the VM is paused, the run waits until it's resumed.
The run uses the VM's own shared folders, clipboard and network, as you set them.

This Mac

The script runs on your Mac, as you. Scripts on this Mac decides whether vmpal and AI agents can make a script run here.

How it runs

Each script runs with the shell of the place it runs:

Where	Language	Runs with
Linux VM	Shell	bash
macOS VM	Shell	zsh
Your Mac	Shell	zsh, or the interpreter in its `#!` line
Windows VM	PowerShell	Windows PowerShell

A shell script runs as a login shell, from the home folder.
Runs use the user's account, not root. They read the login shell's files: ~/.profile in Linux (not ~/.bashrc), and ~/.zprofile in macOS and on your Mac (not ~/.zshrc). So install your tools for every user, or set the PATH in those files.
The exit code decides if a run passed. Exit status 0 means it passed. Any other status means it failed.
PowerShell keeps going after a program fails. So check $LASTEXITCODE after each one.
VMPal copies nothing from your Mac but the script. Your script gets your code itself, for example with git clone.

Run it

Click Run Now in the sidebar or the script's menu. The script runs in each place you chose. If you haven't chosen anywhere yet, VMPal asks where.

To run it somewhere else, hold Option in the script's menu and choose Run On…. VMPal asks where first. It runs the script there, and keeps running it there from then on.

VMPal sends a notification when a hook's run ends, saying how it went. It does the same for Run Now's runs while VMPal isn't the app in front.

History

History, in the sidebar, lists each run. It shows the run's state, how long it took, and why it failed or is waiting.

Show Log opens a run's output.
Stop stops a run. Stop Runs, in the script's menu, stops all of them.
Double-click an item to see all of it, with each run's log as it comes in.

Logs

Logs are on your Mac, in ~/Library/Logs/VMPal/Hub. In the Hub, Help › Show Logs in Finder opens the script's logs.

VMPal keeps each log within 16 MiB. A longer log keeps its start and end.
VMPal keeps the last 50 finished runs of each script, with their logs.

Quitting VMPal

If runs are in progress when you quit VMPal, it asks first, with Stop Runs and Quit. Then it stops the runs and deletes their clones. Runs still waiting when VMPal quits never start. And nothing starts while an update waits to install.

Its settings

To change a script's settings, choose Edit Script… in its menu, or click Edit… beside its name in the sidebar.

Setting	What it does
Language	Shell, or PowerShell for Windows VMs
Timeout	VMPal stops a run that goes on longer. Choose 5 minutes to 6 hours. It's 1 hour by default. With `vmpal`, you can set up to 24 hours
New Message	What happens when the hook gets a new message while a run is in progress. Queue After the Current Run is the default. Cancel the Current Run and Run It is the other choice
Send Output to vmpal.com	A hook's runs send their output to vmpal.com as they go, up to 1 MiB a run

Send Output to vmpal.com sends the output to the License Manager, the account page on vmpal.com. It goes to the account that owns your Mac's license, and that may not be you. On a company's license, the company's account reads the output, and you don't.

In the script's menu, Duplicate copies the script, without its hook. Delete Script… deletes the script, its runs and their logs, and its hook.

The variables

Each run gets these environment variables:

Variable	Value
`VMPAL_SCRIPT_NAME`	The script's name
`VMPAL_RUN_ID`	The run's ID
`VMPAL_TARGET`	Where it runs: `mac`, or the VM's name

A hook's runs also get the message, as VMPAL_MESSAGE_BODY and the others. In PowerShell, they're $env:VMPAL_SCRIPT_NAME and so on.

Limits

One run at a time in each place. A script runs once at a time in each place it runs, with one more run waiting. A newer run takes the waiting run's place.
Two clones at once. At most two runs in clones go at the same time. A script's next clone of a VM waits until VMPal deletes its last one.
Two macOS VMs at once. macOS allows at most two macOS VMs at a time, including the ones you run yourself. When two are running, a run in a macOS VM waits for one to stop.
The VM itself takes one run at a time, whatever its script. A script that runs in the VM itself can be 32,000 bytes at most (as UTF-8). VMPal skips the runs of a longer script, so run that one in a clone.
30 minutes to start. VMPal skips a run that waits 30 minutes to start, such as for its VM to shut down.

Scripts on this Mac

A script on your Mac runs code as you. So VMPal checks a setting when vmpal or an AI agent would make a script run on your Mac. That's when they would:

add your Mac to where a script runs
run a script there now
make a hook for a script that runs there
change the text of a script that runs there

The setting is Settings › AI Agents › Scripts on this Mac:

Choice	What VMPal does
Allow (agents ask you)	The default. VMPal allows it without asking you. Agents are told to ask you first, but VMPal can't check that. So any app on your Mac could run code as you this way
Ask in VMPal	VMPal shows you the script's text and where it runs, and asks you. It asks once for each version of the script
Off	VMPal refuses

The setting doesn't change scripts in VMs, hooks that already run on your Mac, or what you do in the Hub.

With vmpal

vmpal is VMPal's command-line tool, like docker or gh. Its vmpal script commands do what the Hub does:

Command	What it does
`vmpal script create <name> --file <path>`	Saves a script. Choose where it runs with `--run-in <VM>` for a fresh clone of the VM, `--run-in-place <VM>` for the VM itself, and `--host` for this Mac
`vmpal script run <script> --wait`	Runs it now and waits for its runs. Its exit code says whether they passed
`vmpal script log <script>`	Shows the newest run's output
`vmpal script runs <script>`	Lists its runs, with their states and why they failed
`vmpal script edit <script>`	Changes its text, settings or where it runs

vmpal script create "Build" --file build.sh --timeout 30m --run-in "Ubuntu"
vmpal script run "Build" --wait
vmpal script log "Build"

Commands lists the rest. AI agents do the same with VMPal's MCP tools, such as vmpal_create_script, vmpal_run_script and vmpal_get_run_log. They need Let coding agents on this Mac manage all VMs turned on.

Run it from anywhere

A hook is a webhook URL for a script. When anything posts to it, such as a CI job on each push, the script runs. Hooks need a VMPal license. Scripts don't.