Getting Started

Preamp ships as a signed agent for macOS and Windows. Install it once and the agent handles enrollment, hourly backups, and self-updates. Optionally add the MCP server in Claude Code for natural-language control inside your coding session.

Install the agent (recommended)

The Preamp agent is a single signed binary. Hourly backups run via a per-user OS-native scheduler — LaunchAgent on macOS, Task Scheduler on Windows. The agent self-updates opportunistically (signature + integrity verified, smoke-tested before swap, rolls back on failure). No Node.js, no cron.

macOS

The macOS agent is signed and notarized by Apple.

1. Run the installer

curl -fsSL https://preamp.ai/agent/install.sh | bash

The launcher fetches the latest user-mode .pkg, verifies it against the manifest, runs the postinstall (places the binary at ~/.local/share/preamp/bin/preamp, symlinks it to ~/.local/bin/preamp, writes the LaunchAgent plist, bootstraps launchd), and prepares for enrollment.

Note: macOS does not include ~/.local/bin in $PATH by default. If preamp isn’t found after install, add export PATH="$HOME/.local/bin:$PATH" to your shell rc file (e.g. ~/.zshrc), or invoke the agent at its canonical path (~/.local/share/preamp/bin/preamp).

2. Enroll

preamp setup

Opens a browser at app.preamp.ai/device-setup for OAuth-style enrollment. Pick a device name, complete email verification, and the agent writes ~/.preamp/config.json and your device token (mode 0600). Returns control to your terminal when done.

You’re done when you see

✓ Preamp is set up. Hourly backups are scheduled via LaunchAgent.

Log in to app.preamp.ai to see your device, snapshots, and any security findings.

Common issues

crontab -l | grep -v 'preamp-agent-backup' | crontab -

For MDM rollout (JAMF / Kandji / Intune / Mosyle), see the enterprise docs.

Windows

The Windows agent is an x64 MSI signed by Azure Trusted Signing (PublicTrust SIV).

1. Run the installer

Download and double-click the latest signed installer:

https://preamp.ai/agent/Preamp-x64.msi

The MSI installs per-user (no admin required), places the agent at %LOCALAPPDATA%\Programs\Preamp\preamp.exe, adds that directory to your per-user PATH, and creates a Preamp shortcut directly under the Start Menu. See the Windows Installer reference for the full breakdown of what gets installed and how to uninstall.

2. Enroll

When the wizard finishes, leave the Launch Preamp setup checkbox checked and click Finish — preamp setup runs automatically. You can also start it later from the Start Menu shortcut, or from any new cmd.exe / PowerShell session:

preamp setup

The flow opens app.preamp.ai/device-setup in your default browser. Pick a device name, complete email verification, and the agent writes %USERPROFILE%\.preamp\config.json and your device token (%USERPROFILE%\.preamp\token).

You’re done when you see

✓ Preamp is set up. Hourly backups are scheduled via Task Scheduler.

Log in to app.preamp.ai to see your device, snapshots, and any security findings.

Common issues

For Intune-managed rollout on Windows, see the enterprise docs.

MCP server

Adds natural-language control of Preamp inside Claude Code sessions. The MCP server runs at api.preamp.ai/mcp; you register it once and Claude handles enrollment automatically on first use.

1. Confirm Claude Code is installed

claude --version

If command not found, install Claude Code from docs.claude.com first.

2. Add the MCP server

claude mcp add --transport http preamp https://api.preamp.ai/mcp

3. Sign up via Claude

macOS only for the auto-install path. The “Sign me up for Preamp” flow currently drives a curl … | bash shell install, which only runs on macOS. Windows users: install the agent manually first via the Windows MSI, run preamp setup, then come back here and tell Claude “Sign me up for Preamp” — Claude will detect the existing install and bind your Claude Code session to it.

Open a fresh Claude session and tell it:

Sign me up for Preamp.

Claude will install the Preamp agent (~30 seconds, one-time on macOS), open your browser to verify your email, and bind this Claude Code session. Once complete, you can ask things like:

• “What’s my backup status?”
• “Show me my last 10 snapshots.”
• “Restore my Cursor settings from yesterday.”

The local preamp CLI installed during signup gives the same surface from any terminal — run preamp status, preamp snapshots, etc. without opening Claude.

4. Restarting Claude Code

Each time you start a new Claude Code session the MCP connection is fresh. Claude transparently re-runs the session-binding step on your first Preamp request — no re-enrollment, no extra steps.

Common issues

Using /preamp after setup

Once either install path completes, the /preamp slash command is available globally in any Claude Code session. Type /preamp to get your backup status, trigger a manual backup, sync your config from another machine, restore from a snapshot, and more. Natural language also works — say things like “what’s my backup status” or “back up now” and Claude will use the Preamp tools directly.

macOS Installer

Platforms: macOS · Windows

1. Apple notarization check — install.sh verifies the downloaded .pkg is Apple-notarized via spctl --assess before running it. Refuses to install on a notarization failure.

2. Postinstall — Places the agent binary at ~/.local/share/preamp/bin/preamp, symlinks it to ~/.local/bin/preamp for your $PATH, and writes the LaunchAgent plist at ~/Library/LaunchAgents/ai.preamp.agent.plist. If a legacy install at ~/Library/Application Support/Preamp/bin/preamp exists, it is removed and a baseline-rebuild marker is written so the next scheduled backup runs full.

   Note: macOS does not include ~/.local/bin in $PATH by default. If preamp isn’t found after install, add export PATH="$HOME/.local/bin:$PATH" to your shell rc file (e.g. ~/.zshrc), or invoke the agent at its canonical path (~/.local/share/preamp/bin/preamp).

3. LaunchAgent bootstrap — Loads the LaunchAgent into your GUI session via launchctl bootstrap so hourly backups start running immediately. (No cron involved — the LaunchAgent runs even when no terminal is open.)

4. Email verification — preamp setup opens a browser to app.preamp.ai/device-setup, you enter your email, a 6-digit code is sent, you complete verification.

5. Device registration — Generates a cryptographic device token and writes it to ~/.preamp/config.json (mode 0600).

6. Auto-discovery — Scans for Claude Code, ChatGPT, Cursor, Windsurf, Gemini CLI, Aider, and Continue. Codex and GitHub Copilot are coming soon.

7. First backup — Runs an immediate backup of all discovered files. Subsequent backups run hourly via the LaunchAgent installed in step 3.

Windows Installer

Platforms: macOS · Windows

The Preamp Windows agent ships as a signed .msi installer for x64 Windows 10/11. Installation is per-user — no admin elevation required, no shared paths touched, and Add or Remove Programs shows it under the installing user’s account only.

1. Download the MSI

Download the latest signed installer:

https://preamp.ai/agent/Preamp-x64.msi

The MSI is signed via Azure Trusted Signing (PublicTrust SIV). Right-click → Properties → Digital Signatures to verify the publisher reads Rewind Software, Inc. before running it.

2. Run the installer

Double-click the .msi. The installer is a standard WiX FeatureTree wizard — accept the license, accept the install location, click Install.

Because the install is per-user, Windows does not prompt for admin credentials.

SmartScreen note: the installer is signed with a PublicTrust SIV certificate, so SmartScreen should not block it. If you see “Windows protected your PC” on a brand-new release, click More info → Run anyway. This typically only happens during the short reputation-build window after a fresh release; subsequent downloads of the same file go through silently.

3. What gets installed

The PATH entry is registered cleanly — uninstalling Preamp removes it. Open a fresh cmd.exe or PowerShell session after install and preamp will resolve.

4. First-run setup

The final wizard page has a pre-checked Launch Preamp setup checkbox. Click Finish with the box checked and preamp setup runs immediately:

1. Opens app.preamp.ai/device-setup in your default browser.
2. You enter your work email; Preamp emails a 6-digit verification code.
3. You enter the code; the agent writes your device token to %USERPROFILE%\.preamp\token.
4. The agent runs auto-discovery for installed AI assistants (Claude Code, ChatGPT desktop, Cursor, Windsurf, Gemini CLI, Aider, Continue) and runs the first backup.
5. The hourly Scheduled Task starts firing on the next top-of-hour.

If you unchecked the box and clicked Finish, run setup later from the Start Menu (click the Preamp shortcut) or from a terminal:

preamp setup

5. Uninstall

Go to Settings → Apps → Installed apps, find Preamp, click the ⋯ menu, and pick Uninstall.

Uninstall is a clean wipe — the MSI and the agent’s pre-uninstall hook together remove:

• The agent binary and its install directory at %LOCALAPPDATA%\Programs\Preamp\.
• The Start Menu shortcut.
• The per-user PATH entry from HKCU\Environment\PATH.
• The hourly Scheduled Task (Preamp).
• The agent’s data + log directory at %LOCALAPPDATA%\preamp\ (including logs\preamp-backup.log).
• The agent’s runtime state at %USERPROFILE%\.preamp\ (token, config, cached server state).

Past snapshots are unaffected — they’re stored server-side under your account on app.preamp.ai. If you want to preserve a copy of preamp-backup.log for forensics, copy it out of %LOCALAPPDATA%\preamp\logs\ before running the uninstaller.

Common issues

For MDM rollout via Intune or a similar tool, see the enterprise docs.

Configuration Options

Backup frequency

Default is hourly, scheduled via your OS — LaunchAgent on macOS, Task Scheduler on Windows. Change it to one of the supported intervals: 15 minutes, 30 minutes, hourly, or daily.

Every 15 minutes

preamp schedule 15min

Every 30 minutes

preamp schedule 30min

Every hour (default)

preamp schedule hourly

Once per day

preamp schedule daily

The new interval is applied to your OS scheduler — ~/Library/LaunchAgents/ai.preamp.agent.plist (macOS, reloaded automatically) or the Preamp Scheduled Task (Windows, re-registered automatically). No reboot or re-login required.

[!NOTE] For MDM-managed installs on macOS, the schedule is set via the schedule key in the managed-prefs profile and overrides any local change. See the managed preferences reference.

Custom directories

Add additional paths to your backup. Useful for project-level agent files or custom tool settings.

Via Claude Code (natural language)

Say this to Claude:

Also back up ~/my-project/.claude

Via CLI

preamp paths add ~/my-project/.claude

The paths add flow uploads the path as a candidate; auto-approve is enabled by default for user-mode installs, so the path takes effect on the next backup. List current paths with preamp paths list and remove with preamp paths remove <path>.

Credential Storage

The agent stores your device token securely. Where the OS provides a credential manager (macOS Keychain, GNOME Keyring on Linux), the token lives there; on platforms without one, it falls back to a protected token file under your home directory, restricted by the OS’s default per-user permissions or ACLs.

CLI Reference

Webhooks

Subscribe to events and receive HTTP POST notifications at your endpoint. See the API reference for webhook CRUD endpoints.

Event Types

Payload Format

Every delivery is an HTTP POST with Content-Type: application/json.

{
  "event": "backup-complete",
  "timestamp": "2026-03-25T10:30:00.000Z",
  "userId": "usr_abc123",
  "data": {
    "action": "backup_complete",
    "deviceId": "dev_xyz789",
    "metadata": {
      "snapshotId": "snap_abc123",
      "fileCount": 42,
      "totalBytes": 1048576
    }
  }
}

Signature Verification

Always verify the X-Preamp-Signature header before processing a webhook.

Node.js

import crypto from 'node:crypto';

function verifyWebhook(secret, body, signature) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expected, 'hex'),
  );
}

// In your HTTP handler:
app.post('/webhooks/preamp', (req, res) => {
  const signature = req.headers['x-preamp-signature'];
  const rawBody = req.body; // must be raw string

  if (!verifyWebhook(WEBHOOK_SECRET, rawBody, signature)) {
    return res.status(401).send('Invalid signature');
  }

  const payload = JSON.parse(rawBody);
  console.log(`Received: ${payload.event}`);
  res.status(200).send('OK');
});

Python

import hmac
import hashlib

def verify_webhook(secret: str, body: bytes, signature: str) -> bool:
    expected = hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

# In your Flask handler:
@app.route('/webhooks/preamp', methods=['POST'])
def handle_webhook():
    signature = request.headers.get('X-Preamp-Signature', '')
    raw_body = request.get_data()

    if not verify_webhook(WEBHOOK_SECRET, raw_body, signature):
        return 'Invalid signature', 401

    payload = request.get_json()
    print(f"Received: {payload['event']}")
    return 'OK', 200

Slack Integration

If your webhook URL points to hooks.slack.com, Preamp automatically formats the payload as a Slack message:

{
  "text": "[Preamp Backup] *backup-complete*: `backup_complete` (device: dev_xyz789)"
}

Limits & Behavior

Deliveries are dispatched asynchronously. Failed deliveries are not retried — use the test endpoint to verify connectivity before subscribing to production events.