RCPT_SITE_INSTALL2026-11-02

Set up Magic Folder.

You’ll install three free things: Node.js (which Magic Folder runs on), Ollama (the AI that runs on your computer) and Magic Folder itself. The longest part is the AI model download, about 5 GB.

Used every day on a Mac. Every step on this page except installing Ollama and its model is also tested automatically on clean Mac, Windows and Linux machines whenever the code changes. Ollama is too large for those test machines, so jobs that use it are tested by hand on a Mac.

Type the commands in Terminal (in Applications → Utilities). Each black box has a Copy button.

Step 01
Install Node 24
Magic Folder runs on Node.js. Use version 24: newer versions such as 26 aren’t supported yet, and the “LTS” download on nodejs.org is now 26. With Homebrew:
```
brew install node@24
echo 'export PATH="$(brew --prefix node@24)/bin:$PATH"' >> ~/.zshrc
```
Then close Terminal and open it again.
node -v prints v24. and a number.
No Homebrew? Download the .pkg file from nodejs.org/dist/latest-v24.x and open it.
Step 02
Install Ollama, the free local AI
Download Ollama for Mac, move it to Applications and open it. Then get the model (about 5 GB):
```
ollama pull qwen3:8b
```
ollama list shows qwen3:8b.
Step 03
Install Magic Folder
```
npm install -g @agent-receipts/magic-folder
```
magic-folder --help lists the commands.
If you installed Node with the .pkg and see EACCES, run the same command with sudo in front.
Step 04
Create your Magic Folder
```
magic-folder init ~/"Magic Folder"
```
It prints Magic Folder ready, and a Magic Folder appears in your home folder with six job folders.
Step 05
Check everything
```
magic-folder doctor
```
Node, Ollama and qwen3:8b each have a ✓.
Step 06
Start it
```
magic-folder run ~/"Magic Folder" --engine ollama --issuer "Your Business"
```
- --engine ollama runs jobs on Ollama, free, on your computer.
- --issuer "Your Business" is the name printed on your receipts. Use your own.
- --key-url and --verify-url are only for when you host your own verify page. How that works.
It prints Watching …. Leave the window open and drop a file into Fix typos.

After setup

Keep it running

To start Magic Folder every time you log in, and restart it if it stops, paste this into Terminal. Change Your Business first.

mkdir -p ~/Library/LaunchAgents
cat > ~/Library/LaunchAgents/com.agent-receipts.magic-folder.plist <<EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key><string>com.agent-receipts.magic-folder</string>
  <key>ProgramArguments</key>
  <array>
    <string>$(command -v node)</string>
    <string>$(npm root -g)/@agent-receipts/magic-folder/dist/cli.js</string>
    <string>run</string>
    <string>$HOME/Magic Folder</string>
    <string>--engine</string><string>ollama</string>
    <string>--issuer</string><string>Your Business</string>
  </array>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
  <key>StandardOutPath</key><string>$HOME/Library/Logs/magic-folder.log</string>
  <key>StandardErrorPath</key><string>$HOME/Library/Logs/magic-folder.log</string>
</dict>
</plist>
EOF
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.agent-receipts.magic-folder.plist

tail ~/Library/Logs/magic-folder.log shows Watching …. The Ollama app starts at login by itself.

Stop	`launchctl bootout gui/$(id -u)/com.agent-receipts.magic-folder`
Start again	`launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.agent-receipts.magic-folder.plist`
Remove	`launchctl bootout gui/$(id -u)/com.agent-receipts.magic-folder; rm ~/Library/LaunchAgents/com.agent-receipts.magic-folder.plist`

Prefer to start it yourself? This puts a Start Magic Folder launcher on your Desktop. Double-click it to start; it won’t start a second copy.

cat > ~/Desktop/"Start Magic Folder.command" <<EOF
#!/bin/sh
if pgrep -f "magic-folder/dist/cli.js run" >/dev/null; then echo "Already running in the background."; exit 0; fi
echo "Magic Folder is running. Leave this window open."
exec "$(command -v node)" "$(npm root -g)/@agent-receipts/magic-folder/dist/cli.js" run "\$HOME/Magic Folder" --engine ollama --issuer "Your Business"
EOF
chmod +x ~/Desktop/"Start Magic Folder.command"

Type the commands in PowerShell (Start menu → type “PowerShell”). Each black box has a Copy button.

Step 01
Install Node 24
Magic Folder runs on Node.js. Use version 24: newer versions such as 26 aren’t supported yet, and the “LTS” download on nodejs.org is now 26. Download the Windows installer (node-v24.…-x64.msi) from nodejs.org/dist/latest-v24.x, run it and keep the defaults. Then open a new PowerShell window.
node -v prints v24. and a number.
Step 02
Install Ollama, the free local AI
Download Ollama for Windows and run OllamaSetup.exe, or in PowerShell (the model is about 5 GB):
```
irm https://ollama.com/install.ps1 | iex
ollama pull qwen3:8b
```
ollama list shows qwen3:8b.
Step 03
Install Magic Folder
```
npm install -g @agent-receipts/magic-folder
```
magic-folder --help lists the commands.
If PowerShell says running scripts is disabled on this system, run Set-ExecutionPolicy -Scope CurrentUser RemoteSigned, answer Y, and try again.
Step 04
Create your Magic Folder
```
magic-folder init "$HOME\Magic Folder"
```
It prints Magic Folder ready, and a Magic Folder appears in your user folder with six job folders.
Step 05
Check everything
```
magic-folder doctor
```
Node, Ollama and qwen3:8b each have a ✓.
Step 06
Start it
```
magic-folder run "$HOME\Magic Folder" --engine ollama --issuer "Your Business"
```
- --engine ollama runs jobs on Ollama, free, on your computer.
- --issuer "Your Business" is the name printed on your receipts. Use your own.
- --key-url and --verify-url are only for when you host your own verify page. How that works.
It prints Watching …. Leave the window open and drop a file into Fix typos.

After setup

Keep it running

To start Magic Folder each time you log on, paste this into PowerShell. It puts a small starter in your Startup folder that opens Magic Folder in a minimised window. Change Your Business first.

$startup = [Environment]::GetFolderPath('Startup')
Set-Content -Path "$startup\Start Magic Folder.bat" -Encoding ASCII -Value @'
@echo off
if not "%~1"=="min" (start "Magic Folder" /min "%~f0" min & exit /b)
powershell -NoProfile -Command "if (Get-CimInstance Win32_Process -Filter \"Name='node.exe'\" | Where-Object { $_.CommandLine -like '*magic-folder*run*' }) { exit 1 }"
if errorlevel 1 (echo Already running. & timeout /t 5 >nul & exit /b)
echo Magic Folder is running. Leave this window open.
magic-folder run "%USERPROFILE%\Magic Folder" --engine ollama --issuer "Your Business"
'@
Start-Process "$startup\Start Magic Folder.bat"

A minimised Magic Folder window is in the taskbar and says Watching …. Ollama starts at log on by itself.

Stop	Close the “Magic Folder” window
Start again	`Start-Process "$([Environment]::GetFolderPath('Startup'))\Start Magic Folder.bat"`
Remove	`Remove-Item "$([Environment]::GetFolderPath('Startup'))\Start Magic Folder.bat"`

Type the commands in a terminal. Each black box has a Copy button.

Step 01
Install Node 24
Magic Folder runs on Node.js. Use version 24: newer versions such as 26 aren’t supported yet. The easiest way is nvm:
```
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.8/install.sh | bash
```
Close the terminal and open it again, then:
```
nvm install 24
```
node -v prints v24. and a number.
Step 02
Install Ollama, the free local AI
From ollama.com (the model is about 5 GB):
```
curl -fsSL https://ollama.com/install.sh | sh
ollama pull qwen3:8b
```
ollama list shows qwen3:8b.
Step 03
Install Magic Folder
```
npm install -g @agent-receipts/magic-folder
```
magic-folder --help lists the commands.
Step 04
Create your Magic Folder
```
magic-folder init ~/"Magic Folder"
```
It prints Magic Folder ready, and a Magic Folder appears in your home folder with six job folders.
Step 05
Check everything
```
magic-folder doctor
```
Node, Ollama and qwen3:8b each have a ✓.
Step 06
Start it
```
magic-folder run ~/"Magic Folder" --engine ollama --issuer "Your Business"
```
- --engine ollama runs jobs on Ollama, free, on your computer.
- --issuer "Your Business" is the name printed on your receipts. Use your own.
- --key-url and --verify-url are only for when you host your own verify page. How that works.
It prints Watching …. Leave the terminal open and drop a file into Fix typos.

After setup

Keep it running

To run Magic Folder in the background as a systemd user service, paste this. Change Your Business first.

mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/magic-folder.service <<EOF
[Unit]
Description=Magic Folder

[Service]
ExecStart=$(command -v node) $(npm root -g)/@agent-receipts/magic-folder/dist/cli.js run "%h/Magic Folder" --engine ollama --issuer "Your Business"
Restart=on-failure
RestartSec=10

[Install]
WantedBy=default.target
EOF
systemctl --user daemon-reload
systemctl --user enable --now magic-folder

systemctl --user status magic-folder says active (running). To keep it running while you’re logged out too: sudo loginctl enable-linger $USER.

Logs	`journalctl --user -u magic-folder -f`
Stop	`systemctl --user stop magic-folder`
Start again	`systemctl --user start magic-folder`
Remove	`systemctl --user disable --now magic-folder; rm ~/.config/systemd/user/magic-folder.service`

Help

If something goes wrong

“magic-folder: command not found”

Open a new terminal window. If it’s still missing, check that node -v works; if it does, run the install command again.

Wrong Node version

node -v shows lower than 22.16, or 27 or higher: install Node 24 as above. On a Mac with Homebrew, make sure the export PATH=…node@24… line is in ~/.zshrc and open a new window.

doctor says Ollama is not reachable

Start the Ollama app (Mac, Windows) or run ollama serve (Linux), then ollama pull qwen3:8b.

Nothing happens when I drop a file

Magic Folder must be running: magic-folder run … in an open window, or the start-at-login setup. Files are picked up a few seconds after they stop changing. Drop into a job folder such as Fix typos, not into the top folder.

Still stuck? Open an issue on GitHub with what you typed and what it printed.

Remove

Uninstall

npm uninstall -g @agent-receipts/magic-folder

Remove the start-at-login setup first (see “Keep it running”). Your Magic Folder, with its results and receipts, and your signing key in ~/.agent-receipts/magic-folder (Windows: %USERPROFILE%\.agent-receipts\magic-folder) stay until you delete them yourself.

Optional

Use Claude

For bigger jobs, Magic Folder can use Claude with your own Anthropic API key. See Use Claude in the guide on GitHub. API keys only: Anthropic doesn’t allow other products to use claude.ai logins.

Set up Magic Folder.

Install Node 24

Install Ollama, the free local AI

Install Magic Folder

Create your Magic Folder

Check everything

Start it

Keep it running

Install Node 24

Install Ollama, the free local AI

Install Magic Folder

Create your Magic Folder

Check everything

Start it

Keep it running

Install Node 24

Install Ollama, the free local AI

Install Magic Folder

Create your Magic Folder

Check everything

Start it

Keep it running

If something goes wrong

Uninstall

Use Claude