Free knowledge sharing on all things Agentic AI

How to Run Hermes in a macOS Sandbox?

A recipe-style guide to putting Hermes inside a self-contained Linux box on your Mac — with its own Python, its own Node, and exactly one folder shared with the rest of your machine.

Setup time ~30 minutes
Disk budget ~15 GB (cap at 20 GB)
One-time cost Free
Going cost Free

Ingredients

Why sandbox an agent at all?

An agent that can write files, install packages, and run shell commands is useful precisely because it can write files, install packages, and run shell commands. Pointed at your real home directory it will eventually do something you did not intend — pip install a wrong version into your system Python, drop a stray script next to your tax returns, or learn that rm -rf exists.

The cheapest insurance is to run it inside a Linux box that has its own Python, its own Node, its own everything — and exactly one folder shared with the outside world. You drop files in, the agent reads them. The agent writes results out, you pick them up. The blast radius of any mistake is that one folder.

This recipe uses OrbStack as the runtime. It is the shortest path on macOS: one installer, native shared folders over VirtioFS, and resource limits that you can adjust from a settings pane without editing a YAML file. If you prefer a different stack, there are four alternatives at the bottom of this page that get you to the same place.

1 Install OrbStack

The easiest way is Homebrew. If you do not have Homebrew yet, install it first from brew.sh. 

brew install orbstack

Open the OrbStack app once so it can install its kernel extension and virtualisation helpers. The first launch wizard asks whether you want Docker containers, Linux machines, or both — pick both. We use the Linux-machine mode for this recipe; the container mode is handy later.

Why OrbStack and not Docker Desktop? OrbStack uses a fraction of the RAM at idle, boots a Linux VM in roughly a second, and its VirtioFS shared folders are several times faster than Docker Desktop’s gRPC-FUSE bridge. For a long-running agent that reads and writes a shared directory all day, the difference is felt.

2 Cap the sandbox at 20 GB

Open OrbStack → Settings → System and set:

The disk image is sparse, so it only consumes the space it is actually using; the cap is a hard ceiling, not a pre-allocation. If you ever need to reclaim the floor you can run orb prune.

3 Create the shared folder on the Mac side

Pick one folder that will be the only bridge between Hermes and the rest of your machine. Anything outside this folder is invisible to the agent. 

mkdir -p ~/hermes-workspace

By default OrbStack auto-mounts your entire ~ at /mnt/mac/Users/<you> inside Linux machines — convenient, but the exact opposite of what we want for a sandbox. Disable it in Settings → File Sharing by turning off “Mount user home directory”, then add a single explicit mapping:

Why one folder, not the home directory? A scoped mount means the agent literally cannot see ~/Documents, ~/Downloads, or your SSH keys — not because it has been politely asked not to, but because they are not in its filesystem namespace.

4 Create the Linux machine

One command spins up an Ubuntu 24.04 LTS machine called hermes: 

orb create ubuntu:24.04 hermes

And drop into it: 

orb shell -m hermes

Confirm the shared folder is visible: 

ls -la /workspace
# should list whatever you have in ~/hermes-workspace on the Mac

touch /workspace/hello-from-the-sandbox.txt
# the file should appear on the Mac immediately

5 Install your own Python with pyenv

The sandbox ships with the distro Python, but we want a version we control. Install the build tools and pyenv: 

sudo apt update
sudo apt install -y build-essential curl git \
    libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev \
    libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev \
    libffi-dev liblzma-dev

curl https://pyenv.run | bash

Wire pyenv into your shell — append to ~/.bashrc: 

export PYENV_ROOT="$HOME/.pyenv"
[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"

Reload your shell and install a Python: 

exec bash
pyenv install 3.12.7
pyenv global 3.12.7
python --version
# Python 3.12.7

6 Install your own Node with fnm

fnm is a fast, single-binary Node version manager — nvm without the sluggish shell startup. 

curl -fsSL https://fnm.vercel.app/install | bash
exec bash

fnm install 22
fnm default 22
node --version
# v22.x.x
npm --version

Both python and node now live entirely inside the sandbox. Nothing you do in here touches the Python or Node on your Mac.

7 Install Hermes

Clone Hermes into the sandbox — not into the shared folder. Code lives inside the box; only data goes through /workspace. 

cd ~
git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

python -m venv .venv
source .venv/bin/activate
pip install -e .

Hermes picks up its working directory from the HERMES_WORKSPACE environment variable. Point it at the shared folder: 

export HERMES_WORKSPACE=/workspace
echo 'export HERMES_WORKSPACE=/workspace' >> ~/.bashrc

8 Run Hermes and verify the seam

Start the agent in interactive mode: 

hermes run --workspace /workspace

Ask it to do something that touches the filesystem — say, “create a file called notes.md with a one-line summary of today’s date”. Then, on the Mac side: 

cat ~/hermes-workspace/notes.md

That file moved from inside the sandbox straight onto your Mac, with no copy step. Conversely, drop a file into ~/hermes-workspace from your normal editor and ask Hermes to read it — same channel, in the opposite direction.

For a one-shot run from your Mac shell (without entering the sandbox first), the equivalent is: 

orb run -m hermes -- bash -lc \
    'cd ~/hermes-agent && source .venv/bin/activate && hermes run'

Cleanup & teardown

The sandbox is disposable by design. If Hermes ever gets into a state you do not like, you can throw the whole thing away without losing the shared folder: 

# pause without deleting
orb stop hermes

# wipe the box completely (the shared folder on the Mac is untouched)
orb delete hermes

# rebuild from step 4 onwards

What you end up with

A Linux machine on your Mac that boots in about a second, weighs under 4 GB of RAM, and caps out at 20 GB of disk. Inside it is a Python you chose, a Node you chose, and a freshly installed Hermes. Outside it is your normal macOS Sonoma, untouched. The two sides exchange files through exactly one folder: ~/hermes-workspace on the Mac, /workspace on the Linux side.

Alternatives

OrbStack is the path of least resistance, but every team has a preferred container or VM stack. Each of these gets you to the same outcome — one shared folder, own Python, own Node, capped disk:

Further reading