Install Pomme

This page shows you how to build Pomme from source, install it, and confirm that your shell runs the installed executable.

Before you begin

Check that your Mac meets the system requirements, including a full Xcode installation and the project’s Developer ID Application certificate.
Clone the Pomme repository.

Build and install

The Scripts/build-local.sh script builds a signed Release executable and installs it. To build and install Pomme, follow these steps:

In a terminal, go to the root of the Pomme repository.
Run the build script as your normal user. Don’t use sudo.
Terminal window
```
bash Scripts/build-local.sh
```
The script does the following:
- Builds the arm64 Release configuration with xcodebuild.
- Signs the executable with the project’s Developer ID certificate, the com.github.weswhet.pomme signing identifier, Hardened Runtime, and a secure timestamp.
- Verifies the signature, and checks that the only entitlement is com.apple.security.virtualization.
- If a pomme executable is already installed, checks that the new build has the same designated requirement before it replaces the old one.
- Keeps a copy of each signed executable, indexed by its SHA-256 digest, so that an interrupted VM creation can resume with the exact agent it started with.
- Copies the executable to ~/.local/bin/pomme in one atomic step.
If any check fails, the script stops and leaves the installed executable unchanged.

To install to a different directory, pass an absolute path with --install-dir:

bash Scripts/build-local.sh --install-dir INSTALL_DIRECTORY

Replace INSTALL_DIRECTORY with the absolute path of the directory that receives the pomme executable.

Add the install directory to your PATH

If ~/.local/bin isn’t on your PATH, the script prints a reminder. To add it for zsh, add the following line to ~/.zprofile, and then open a new terminal window:

export PATH="$HOME/.local/bin:$PATH"

Verify the installation

To confirm that your shell runs the executable you just installed, follow these steps:

Check which executable your shell finds:
Terminal window
```
command -v pomme
```
The output is the path of the installed executable:
```
/Users/USERNAME/.local/bin/pomme
```
Check the version:
Terminal window
```
pomme --version
```
The output shows the version and the commit that the executable was built from:
```
pomme 0.1.0 (e1f331d)
```
Optional: list the available commands:
Terminal window
```
pomme --help
```

Keep Keychain access across rebuilds

Pomme stores each VM’s agent credential in your login Keychain. macOS grants Keychain access based on the executable’s code-signing designated requirement, not on its file hash. As long as each build uses the same signing identifier, team, and certificate, a rebuilt pomme keeps access to the Keychain items that earlier builds created.

For this reason, don’t substitute an ad hoc, Apple Development, or unsigned build for the installed executable. The Debug build configuration is signed ad hoc and can’t read the credentials of existing VMs.

About package installs

The repository can also produce an installer package. A package install places the host executable at /usr/local/bin/pomme. Inside each guest, the agent is installed at /usr/local/libexec/pomme and runs under the launchd label com.github.weswhet.pomme.agent. The package isn’t published for the 0.1.0 release.

Uninstall Pomme

To remove the pomme executable, delete it:

rm ~/.local/bin/pomme

Removing the executable doesn’t delete your VMs, templates, or restore images. Pomme stores them in ~/Library/Application Support/pomme. For the layout of that directory, see Files and paths.