Install and update#

Everything Get started skips: platforms, manual downloads, running as a service, updates, the app builds and uninstalling.

What you need#

• Linux amd64/arm64, WSL2, or an Apple Silicon Mac
• curl, tar, and sha256sum (Linux) or shasum (macOS)
• tmux on PATH
• At least one agent CLI on PATH and already signed in: claude, codex, cursor-agent, grok, pi or opencode. One is enough.

Install the daemon#

curl -fsSL https://raw.githubusercontent.com/daoleno/mewla/main/install.sh | sh

The installer picks the newest release for your platform, downloads the archive and its SHA256SUMS, verifies the checksum, and installs mewla into a user-owned directory on your PATH (or ~/.local/bin). It never uses sudo, installs packages, installs agent CLIs, signs in anywhere or sends telemetry. When it finishes, it runs mewla doctor.

If mewla is already installed, the same command runs mewla update instead, unless you set MEWLA_VERSION or MEWLA_INSTALL_DIR.

Options, set as environment variables on sh:

curl -fsSL https://raw.githubusercontent.com/daoleno/mewla/main/install.sh | MEWLA_INSTALL_DIR="$HOME/bin" sh

If the installer added a directory to your shell profile, open a new terminal or run the export PATH=... line it printed.

Manual download#

Download the archive for your host and SHA256SUMS from the GitHub Releases, then verify and install:

# Linux (use mewla-linux-arm64.tar.gz on ARM)
grep 'mewla-linux-amd64.tar.gz$' SHA256SUMS | sha256sum -c -
tar -xzf mewla-linux-amd64.tar.gz

# macOS
grep 'mewla-darwin-arm64.tar.gz$' SHA256SUMS | shasum -a 256 -c -
tar -xzf mewla-darwin-arm64.tar.gz

mkdir -p ~/.local/bin
install -m 755 mewla ~/.local/bin/mewla
~/.local/bin/mewla doctor

On macOS, install tmux with brew install tmux. If macOS blocks the binary, confirm it came from an official Mewla release, then run xattr -d com.apple.quarantine ~/.local/bin/mewla.

Supported platforms#

The installer stops on an unsupported platform before downloading anything.

Check the host#

mewla doctor          # tmux, state directory, listen port, agent CLIs
mewla doctor --json

mewla doctor exits nonzero when the host is not ready and says why. It never installs packages or prints credentials.

To write an executor configuration interactively, run mewla setup. See Agents and models.

Update#

mewla update --check  # is there a newer release?
mewla update          # verify and install it

mewla update checks the release's signed manifest and the archive checksum before it replaces the binary. It does not restart a running daemon; stop and start mewla when convenient. On macOS with the service installed, it also replaces Mewla.app and restarts the service, keeping your address, directories and PATH. Your tmux sessions and agents keep running.

Keep it running#

mewla is the whole runtime. Run it in a terminal or a tmux window, or let Mewla start it for you: a user service on Linux with systemd, a LaunchAgent on macOS.

mewla boot install          # this binary, default state and address
mewla boot install -lan     # same, listening on the private network
mewla boot install -dry-run # print the service without installing it
mewla boot status
mewla boot uninstall

mewla boot install refuses to run as root and refuses to start a second daemon on a state directory that is already in use; stop the running mewla first. Restarting the service never stops your tmux sessions or agents.

• Linux: to start it before you log in, enable lingering with loginctl enable-linger (the command tells you when this is needed).
• macOS: it starts when you log in and runs in your login session, the one that owns the screen and the privacy permissions. After a restart, log in once for Mewla to start. Output goes to ~/.mewla/logs/launchd.log. The service runs a copy of the binary in ~/Applications/Mewla.app, so System Settings and permission prompts show Mewla's name and icon. The command you type stays where you installed it.

mewla boot install signs Mewla.app with a code-signing identity that it creates on this Mac the first time, so you grant Screen Recording and Accessibility once and they stay granted after updates. No Apple account is involved, and nothing asks you anything. The private key never leaves this Mac: it lives in its own keychain, ~/Library/Keychains/mewla-signing.keychain-db, with a random password in ~/Library/Application Support/Mewla/signing/. mewla boot status shows how Mewla.app is signed. If the identity can't be used, Mewla signs ad hoc instead, and macOS asks for the permissions again after each update.

Do not run the daemon as root.

Defaults#

To use another state directory, pass the same -state-dir to every command:

mewla -state-dir /path/to/state
mewla pair -state-dir /path/to/state

Install the app#

Android#

Download mewla-android-arm64-v<version>.apk and SHA256SUMS from the GitHub Releases and verify the APK:

sha256sum -c SHA256SUMS --ignore-missing

The APK supports 64-bit ARM phones (arm64-v8a) only. Android asks you to allow installs from your browser or file manager, and Play Protect may warn because Mewla is not on the Play Store. The official signing certificate's SHA-256 fingerprint is:

C2:FC:5B:09:B3:86:92:EE:70:59:71:1F:E7:ED:B8:79:
4C:E3:65:FE:1C:7A:06:AB:95:4E:5D:D1:BD:CD:A4:FD

Update the app#

Mewla looks for a newer release on its own, at launch and when you come back to it (at most every six hours). Nothing shows while you're up to date. When a newer release exists, a small dot appears on the menu and on Settings, and Settings → About reads Update to v. Tap that row to download the APK. Mewla checks the release's signed manifest and the APK's SHA-256 before it opens the Android installer. The first time, Android asks you to let Mewla install apps. Allow it, come back, and the installer opens. If a download fails, tap the row to retry. Versions before 0.2.9 need one manual install as above; 0.2.9 and 0.2.10 show the update in Settings → About only.

Builds take their update channel from MEWLA_ANDROID_DISTRIBUTION at build time: github-apk (default), play-store or none. Store and none builds, and iOS, leave updates to the store and show the version only.

iOS#

Mewla Preview 0.2.4 (42) is uploaded and awaiting Apple Beta App Review as of 2026-10-10. The new TestFlight public link will accept testers after Apple approves a build in the group. Until then, build the app from source on an Apple Silicon Mac.

Build the iOS app from source#

You need full Xcode, an iOS Simulator runtime or a signed device target, CocoaPods, Bun, and network access for the first native build. Installing on a physical iPhone also needs an Apple development team.

Clone the source, then from the repository root:

git clone https://github.com/daoleno/mewla.git && cd mewla
bun install
bun run native:build:ios     # builds the pinned terminal library
bun run native:verify:ios
cd app
bunx expo prebuild --platform ios --clean
cd ios && pod install && cd ..
bun run ios

You can also open app/ios/Mewla.xcworkspace in Xcode after pod install. The app targets iOS 16.4 or newer and asks for local-network access (to reach your daemon) and camera access (to scan pairing codes).

Web UI#

The daemon also serves the app as a web page for a browser on the same computer or behind HTTPS. See In a browser.

Build the daemon from source#

With the Go version named in daemon/go.mod and Bun installed, from the repository root:

bun install
bun run daemon:build   # writes bin/mewla
./bin/mewla doctor

A source build serves a placeholder instead of the web UI unless you first run bun run web:build.

Uninstall#

1. Run mewla boot uninstall if you installed the service, and stop mewla. On macOS this also removes ~/Applications/Mewla.app. It keeps the signing identity, so a later install keeps your permissions. To remove the identity too, run security delete-keychain ~/Library/Keychains/mewla-signing.keychain-db and rm -r ~/Library/Application\ Support/Mewla/signing, then remove Mewla from Screen & System Audio Recording and Accessibility in System Settings → Privacy & Security.
2. Delete the binary (command -v mewla shows where it is).
3. Optionally delete ~/.mewla. It holds the daemon's identity, paired devices, Work and Brain data; deleting it unpairs every phone.