Skip to main content
Requirements: macOS (Apple Silicon or Intel) with Git installed

​
Quick Install (Homebrew)

1

Install Schaltwerk

brew install --cask 2mawi2/tap/schaltwerk
2

Launch the app

open -a Schaltwerk

​
Manual Installation

Prefer manual installation? Download the latest release and install manually.
1

Download the application

Go to the Releases page and download Schaltwerk-<version>-macos-universal.app.tar.gz
2

Extract and install

# Extract the archive
tar -xzf Schaltwerk-*-macos-universal.app.tar.gz

# Move to Applications folder
mv Schaltwerk.app /Applications/

# Remove quarantine attribute
xattr -cr /Applications/Schaltwerk.app
3

Launch from Applications

Open Finder, navigate to Applications, and double-click Schaltwerk

​
First Launch Setup

Since Schaltwerk is distributed without an Apple Developer certificate, macOS Gatekeeper will block the initial run.
1

Attempt first launch

Try launching Schaltwerk from your terminal or by double-clicking the app. You’ll see a security warning.
2

Open System Settings

Navigate to System Settings → Privacy & Security
3

Approve the application

  1. Scroll down to find: “Schaltwerk was blocked from use because it is not from an identified developer”
  2. Click Open Anyway beside the warning
  3. Enter your password if prompted
4

Confirm launch

Launch Schaltwerk again and click Open when the confirmation dialog appears
After approving once, Schaltwerk will launch normally on future runs.
Next step: Your First Session to create and run an agent

​
Automatic Updates

Schaltwerk checks for updates on startup and applies them automatically by default. You can:
  • Toggle automatic installs in Settings → Version
  • Trigger a manual check at any time with the “Check for updates” button
If an update fails because macOS cannot replace the existing bundle, reopen Schaltwerk directly from /Applications or reinstall from the latest tarball. A toast notification appears once an update has been installed—restart Schaltwerk to launch the new build.

​
Where Schaltwerk Stores Data

Location: ~/Library/Application Support/schaltwerk/settings.jsonStores agent binaries, CLI args, and personal defaults
Location: ~/Library/Application Support/schaltwerk/<project-name>/database.dbStores sessions, specs, and project-level environment variables
Location: <repo>/.schaltwerk/worktrees/<session-name>/Created for each running session and removed when you cancel
Location: ~/Library/Application Support/schaltwerk/logs/Development builds: Keep 3 days of logs (cleaned on startup)Production builds: File logging disabled by default. Enable with:
SCHALTWERK_ENABLE_LOGS=1 open /Applications/Schaltwerk.app
Retention: Adjust retention window (default 72 hours):
SCHALTWERK_LOG_RETENTION_HOURS=168 open /Applications/Schaltwerk.app

​
Development Setup (Optional)

If you plan to build or extend Schaltwerk from source: 
git clone https://github.com/2mawi2/schaltwerk.git
cd schaltwerk
bun install
# or: npm install
bun run tauri:dev
# or: npm run tauri:dev
Use bun run test (or npm run test) to run the full validation suite (TypeScript linting, cargo clippy, cargo test, and a release build check).

​
Troubleshooting

Remove the quarantine attribute:
xattr -cr /Applications/Schaltwerk.app
Re-sign the application:
codesign --force --deep -s - /Applications/Schaltwerk.app
Check if it was installed to the Homebrew prefix:
ls -la $(brew --prefix)/bin/schaltwerk
  1. Go to System Settings → Privacy & Security → Developer Tools
  2. Add Terminal.app or your preferred terminal
  3. Restart Schaltwerk
Schaltwerk runs an API server on port 8547. Find and kill the conflicting process:
# Find what's using the port
lsof -i :8547

# Kill the process if needed
kill -9 <PID>

​
Uninstallation

  • Homebrew
  • Manual
brew uninstall schaltwerk

​
Security Considerations

Schaltwerk is distributed without an Apple Developer certificate to keep it free and open. The ad-hoc signing provides basic code integrity verification and protection against tampering.

​
What Permissions Does Schaltwerk Need?

  • File System Access: To read and write session files
  • Process Spawning: To create terminal sessions (PTY)
  • Network Access: Local API server on port 8547
  • No Special Entitlements: No camera, microphone, or contacts access

​
Is It Safe?

All code is open source and auditable
No external network connections (only localhost)
No telemetry or data collection
Built and signed via GitHub Actions for transparency