Skip to main content

Installation

Get mahpastes running on your system in a few minutes.

Download Pre-built Release​

The easiest way to install mahpastes is to download a pre-built release.

  1. Go to the Releases page
  2. Download mahpastes-darwin-universal.dmg (works on Intel and Apple Silicon)
  3. Open the downloaded .dmg file
  4. Drag mahpastes.app to your Applications folder
  5. On first launch, right-click the app and select "Open" to bypass Gatekeeper
First Launch on macOS

Since mahpastes is not signed with an Apple Developer certificate, macOS may show a security warning. Right-click the app and select "Open" the first time to allow it to run.

Build from Source​

For the latest features or to contribute, build mahpastes from source.

Prerequisites​

Before building, install these dependencies:

DependencyVersionPurpose
Go1.24+Backend language
Node.js18+Frontend build tools
Wails CLI2.xDesktop app framework

Install Wails CLI​

go install github.com/wailsapp/wails/v2/cmd/wails@latest

Verify the installation:

wails doctor

This command checks your environment and reports any missing dependencies.

Clone and Build​

# Clone the repository
git clone https://github.com/egeozcan/mahpastes.git
cd mahpastes

# Install frontend dependencies
cd frontend && npm install && cd ..

# Build for your current platform
wails build

# The app will be in build/bin/

Using the Makefile​

The project includes a Makefile with convenient targets:

make dev        # Start dev server with hot reload
make build      # Clean production build
make clean      # Remove build artifacts
make install    # Build, kill running app, install to /Applications, launch
make uninstall  # Remove installed app
make bindings   # Regenerate frontend bindings after Go changes
make test       # Run e2e tests
make help       # Show all targets

Install the Built App​

# Using make (recommended - also updates bundled plugins)
make install

# Or manually
cp -R build/bin/mahpastes.app /Applications/
xattr -cr /Applications/mahpastes.app
# Copy bundled plugins
mkdir -p ~/Library/Application\ Support/mahpastes/plugins
cp plugins/*.lua ~/Library/Application\ Support/mahpastes/plugins/

Install the CLI (mp)​

The mp CLI is a standalone binary that talks to mahpastes over the REST API. It requires no CGo and cross-compiles for macOS, Linux, and Windows.

Build and Install​

make mp            # Build for current platform
make mp-install    # Install to your user bin dir (or GOBIN if set)
make mp-cross      # Cross-compile for all platforms

Default install locations:

  • macOS/Linux: ~/.local/bin unless GOBIN is set
  • Windows: GOBIN, then %GOPATH%\bin, then %USERPROFILE%\go\bin

On macOS and Linux, if ~/.local/bin is not already in your PATH, add it in your shell profile:

export PATH="$HOME/.local/bin:$PATH"

On Windows, make sure the resolved install directory is in your PATH.

If you want a different location, override the target directory:

make mp-install MP_INSTALL_DIR=/usr/local/bin

Configure API Access​

The CLI authenticates with an API key. Generate one in the desktop app:

  1. Open the menu drawer (press M or click the menu button) and click API
  2. Start the API server if it is not already running
  3. Create a new API key

Then set the environment variable:

export MP_API_KEY=mp_your_key_here
tip

Add the export to your shell profile (~/.zshrc, ~/.bashrc) so it persists across sessions.

The CLI connects to http://localhost:44557 by default. Override with MP_API_URL if needed.

Verify connectivity:

mp api status

Verify Installation​

Launch mahpastes. You should see an empty gallery ready to receive your first clips.

Try pasting something:

  1. Copy some text or an image to your clipboard
  2. Focus the mahpastes window
  3. Press Cmd + V

Your first clip should appear in the gallery.

Next Steps​