# Install and connect Zuse

> Install Zuse on macOS or x64 Linux and make a supported coding-agent CLI available.

Canonical URL: https://docs.zuse.sh/start/install



Zuse ships for macOS and x64 Linux. It uses coding-agent installations already available on your computer, so the first launch checks which supported CLIs are installed and authenticated.

## Install the app [#install-the-app]

### macOS [#macos]

1. Download the current macOS build from [zuse.sh/download](https://zuse.sh/download).
2. Open the downloaded disk image and move Zuse to **Applications**.
3. Launch Zuse. The onboarding flow opens automatically on a fresh installation.

Zuse ships as a signed, notarized universal app for Apple silicon and Intel Macs. Updates are offered in the app when a newer release is available.

### Debian and Ubuntu [#debian-and-ubuntu]

Install the latest x64 `.deb` release from a terminal:

```bash
curl -fsSL https://raw.githubusercontent.com/swarajbachu/zuse/main/scripts/install-linux.sh | sh
```

The installer verifies the GitHub-published SHA-256 digest before invoking `apt`. The package installs the Secret Service and Avahi runtime dependencies.

### Other Linux distributions [#other-linux-distributions]

Download the x64 `.AppImage` from [GitHub Releases](https://github.com/swarajbachu/zuse/releases/latest), make it executable, and launch it:

```bash
chmod +x Zuse-*-linux-x86_64.AppImage
./Zuse-*-linux-x86_64.AppImage
```

AppImage users must provide a Secret Service implementation such as GNOME Keyring or KWallet. Install `avahi-publish-service` if you want nearby-device discovery.

## Connect a provider [#connect-a-provider]

Zuse supports Claude Code, Codex, Grok, Gemini, Cursor, OpenCode, and Kiro. You need at least one provider's CLI installed and signed in.

During onboarding, Zuse shows the providers it detects. A provider may be:

* **Ready** — installed, authenticated, and compatible.
* **Needs attention** — usable, but an update or authentication check needs review.
* **Unavailable** — missing, signed out, or below a required CLI version.

Open **Settings → Providers** at any time to install, sign in, update, enable, or disable providers. Authentication is performed through each provider's supported flow. App-managed API keys are stored in macOS Keychain or Linux Secret Service, not in Zuse's settings JSON.

## Open a repository [#open-a-repository]

Choose **Open project…** and select a folder. Git repositories get the full worktree, Changes, branch, and pull-request workflow. A plain folder can still be used for agent sessions, files, and terminal work, and Zuse can offer to initialize Git when you need version control.

## If a provider is not ready [#if-a-provider-is-not-ready]

1. Open **Settings → Providers** and inspect its status.
2. Confirm its CLI runs from your normal shell.
3. Complete the provider's sign-in flow.
4. Apply an offered update if Zuse reports an incompatible version.
5. Return to the project and create a new session.

Provider authentication and model availability can change outside Zuse. Refresh provider status after changing an installation or account.