Installation

Get Schaltwerk running on your system

Requirements: macOS (Apple Silicon or Intel), Windows 10/11, or Linux with Git installed

Installation

macOS

Quick Install (Homebrew)

1. Install Schaltwerk

   brew install --cask 2mawi2/tap/schaltwerk
   
2. Launch the app

   open -a Schaltwerk
   

Manual Installation

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.

Windows

WSL not yet supported - Schaltwerk runs natively on Windows. WSL (Windows Subsystem for Linux) support is planned for a future release.

1. Download the installer

   Go to the Releases page and download Schaltwerk-<version>-windows-x64.msi or Schaltwerk-<version>-windows-x64.exe

2. Run the installer

   Double-click the downloaded file and follow the installation wizard

3. Launch Schaltwerk

   Find Schaltwerk in the Start menu or on your desktop and launch it

First Launch Setup

Windows may show a SmartScreen warning since Schaltwerk is not signed with an EV certificate.

1. If SmartScreen appears

   Click More info then Run anyway to proceed

2. Allow firewall access

   If prompted, allow Schaltwerk network access for the local API server (port 8547)

Linux

Linux builds are currently in beta. Download from the releases page.

1. Download the package

   Go to the Releases page and download the appropriate package for your distribution:

   • .deb for Debian/Ubuntu
   • .rpm for Fedora/RHEL
   • .AppImage for universal compatibility
2. Install the package

   # Debian/Ubuntu
   sudo dpkg -i Schaltwerk-*.deb
   
   # Fedora/RHEL
   sudo rpm -i Schaltwerk-*.rpm
   
   # AppImage (make executable)
   chmod +x Schaltwerk-*.AppImage
   
3. Launch Schaltwerk

   Run from your application menu or terminal:

   schaltwerk
   

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

A toast notification appears once an update has been installed—restart Schaltwerk to launch the new build.

Troubleshooting update failures

macOS: If an update fails because the system cannot replace the existing bundle, reopen Schaltwerk directly from /Applications or reinstall from the latest tarball.

Windows: If an update fails, try running the installer again as Administrator, or download the latest installer from the releases page.

Where Schaltwerk Stores Data

App Settings

macOS: ~/Library/Application Support/schaltwerk/settings.json

Windows: %APPDATA%\schaltwerk\settings.json

Linux: ~/.config/schaltwerk/settings.json

Stores agent binaries, CLI args, and personal defaults

Project State

macOS: ~/Library/Application Support/schaltwerk/<project-name>/database.db

Windows: %APPDATA%\schaltwerk\<project-name>\database.db

Linux: ~/.local/share/schaltwerk/<project-name>/database.db

Stores sessions, specs, and project-level environment variables

Git Worktrees

Location: <repo>/.schaltwerk/worktrees/<session-name>/

Created for each running session and removed when you cancel (same on all platforms)

Logs

macOS: ~/Library/Application Support/schaltwerk/logs/

Windows: %APPDATA%\schaltwerk\logs\

Linux: ~/.local/share/schaltwerk/logs/

Development builds: Keep 3 days of logs (cleaned on startup)

Production builds: File logging disabled by default. Enable with:

# macOS
SCHALTWERK_ENABLE_LOGS=1 open /Applications/Schaltwerk.app

# Windows (PowerShell)
$env:SCHALTWERK_ENABLE_LOGS=1; & "C:\Program Files\Schaltwerk\Schaltwerk.exe"

# Linux
SCHALTWERK_ENABLE_LOGS=1 schaltwerk

Retention: Adjust retention window (default 72 hours) using the SCHALTWERK_LOG_RETENTION_HOURS environment variable.

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

macOS

Schaltwerk is damaged and can't be opened

Remove the quarantine attribute:

xattr -cr /Applications/Schaltwerk.app

The application Schaltwerk can't be opened

Re-sign the application:

codesign --force --deep -s - /Applications/Schaltwerk.app

App doesn't appear in Applications after Homebrew install

Check if it was installed to the Homebrew prefix:

ls -la $(brew --prefix)/bin/schaltwerk

Terminal permissions issues

1. Go to System Settings → Privacy & Security → Developer Tools
2. Add Terminal.app or your preferred terminal
3. Restart Schaltwerk

Port 8547 already in use

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>

Windows

SmartScreen blocks the application

Windows SmartScreen may block unsigned applications. Click More info then Run anyway to proceed.

Port 8547 already in use

Schaltwerk runs an API server on port 8547. Find and kill the conflicting process:

# Find what's using the port
netstat -ano | findstr :8547

# Kill the process (replace PID with the actual process ID)
taskkill /PID <PID> /F

Firewall blocks Schaltwerk

If Windows Firewall blocks Schaltwerk:

1. Open Windows Security → Firewall & network protection
2. Click Allow an app through firewall
3. Find Schaltwerk and enable both Private and Public networks

WSL repositories not working

WSL support is not yet available. Schaltwerk currently only works with native Windows Git repositories. Use repositories cloned directly in Windows (not within WSL).

Linux

AppImage won't run

Make sure the AppImage is executable:

chmod +x Schaltwerk-*.AppImage

If you get a FUSE error, install FUSE or extract the AppImage:

./Schaltwerk-*.AppImage --appimage-extract
./squashfs-root/AppRun

Port 8547 already in use

Schaltwerk runs an API server on port 8547. Find and kill the conflicting process:

# Find what's using the port
ss -tlnp | grep :8547

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

Uninstallation

macOS (Homebrew)

brew uninstall schaltwerk

macOS (Manual)

# Remove the application
rm -rf /Applications/Schaltwerk.app

# Remove application support files
rm -rf ~/Library/Application\ Support/schaltwerk

# Remove logs
rm -rf ~/Library/Logs/schaltwerk

Windows

1. Open Settings → Apps → Installed apps
2. Find Schaltwerk and click Uninstall
3. Optionally remove data:

# Remove application data
Remove-Item -Recurse -Force "$env:APPDATA\schaltwerk"

Linux

# Debian/Ubuntu
sudo apt remove schaltwerk

# Fedora/RHEL
sudo dnf remove schaltwerk

# Remove data
rm -rf ~/.config/schaltwerk
rm -rf ~/.local/share/schaltwerk

Security Considerations

Schaltwerk is distributed without code signing certificates (Apple Developer on macOS, EV certificate on Windows) to keep it free and open. Ad-hoc signing provides basic code integrity verification.

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