go-iap-mac

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

★ 20 Open GitHub ↗

IAP Tunnel Manager is a macOS app written in Go that simplifies managing Google Cloud IAP TCP tunnels for Windows VMs. It lets you save connections, run multiple tunnels, manage RDP bookmarks, and rotate Windows credentials without using gcloud.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Native macOS client for Google Cloud IAP.
IAP Desktop alternative for macOS.
Connect to GCP VMs over RDP via IAP without Windows.

Google provides IAP Desktop only for Windows.
macOS users are forced to use CLI (gcloud iap tunnel) or Windows VM.

![IAP Tunnel Manager](https://raw.githubusercontent.com/kvysotskyi/go-iap-mac/main/docs/screenshots/mainWindow.png)

## Access Windows VMs from anywhere

IAP Tunnel Manager uses [Identity-Aware Proxy (IAP)](https://cloud.google.com/iap/docs/tcp-forwarding-overview) to connect to VM instances so that you can:

* Connect to VM instances that don't have a public IP address
* Connect from anywhere over the internet
* Apply zero-trust security to your VMs

The application automatically manages IAP TCP tunnels for you, finding free local ports and handling the connection lifecycle.

## Connect to Windows VMs with Remote Desktop

IAP Tunnel Manager makes it easy to establish RDP connections:

* **Auto Port Selection** - Automatically finds free local ports for tunnels
* **Copy RDP Address** - Quick copy of `localhost:<port>` for any RDP client
* **Real-time Logs** - View tunnel connection status and diagnostics
* **One-Click FreeRDP Connection** - Connect instantly with FreeRDP using credentials from Keychain
* **Open Windows App** - Launch Microsoft Windows App directly with one click

## Manage VMs across projects

IAP Tunnel Manager gives you a consolidated view of your VMs:

* **Live Search** - Filter projects and VMs as you type
* **Tunnel Management** - Start, stop, and monitor tunnel status
* **Save Connections** - Save frequently used connections for quick access
* **Multi-project Support** - Browse VMs across all your Google Cloud projects

## Windows App Integration

If you have [Microsoft Windows App](https://apps.apple.com/us/app/windows-app/id1295203466?mt=12) installed, IAP Tunnel Manager can automatically create RDP bookmarks with credentials.

### Create a bookmark

Click the **"..."** menu and select **"Create Windows App Bookmark"**:

### Configure bookmark options

Choose to generate a new Windows password and store it securely in macOS Keychain:

### Credentials saved

The password is generated, saved to Keychain, and the bookmark is created in Windows App:

### Ready to connect

Your bookmark appears in Windows App, ready to use:

## FreeRDP One-Click Connection

IAP Tunnel Manager includes built-in support for FreeRDP, allowing you to connect to Windows VMs with a single click. FreeRDP is an open-source Remote Desktop Protocol client that provides excellent performance and features on macOS.

### Quick Connect with FreeRDP

Once you have a saved connection with credentials stored in macOS Keychain:

1. **Start the tunnel** - Click "Start Tunnel" to establish the IAP connection
2. **Click "Connect with FreeRDP"** - The app automatically launches FreeRDP with:
   - Pre-configured connection settings
   - Credentials retrieved from macOS Keychain
   - Optimized display settings (dynamic resolution, graphics acceleration)
   - Clipboard and sound support enabled

### Installing FreeRDP

If FreeRDP is not installed, install it using Homebrew:

```bash
brew install freerdp
```

The app automatically detects FreeRDP installation in common locations (`/opt/homebrew/bin/sdl-freerdp`, `/usr/local/bin/sdl-freerdp`, or `/usr/bin/sdl-freerdp`).

### FreeRDP Features

When connecting via FreeRDP, you get:

* **Dynamic Resolution** - Automatically adjusts to your display
* **Graphics Acceleration** - Hardware-accelerated rendering for smooth performance
* **Clipboard Integration** - Copy and paste between macOS and Windows
* **Audio Support** - Redirect audio from Windows VM to your Mac
* **Secure Credential Storage** - Passwords stored securely in macOS Keychain

## Use with Claude (MCP)

The same Go binary set ships **`iap-mcp`**, a [Model Context Protocol](https://modelcontextprotocol.io) server that exposes every IAP Tunnel Manager capability as MCP tools and resources. Wire it into Claude Desktop, Claude Code, or Cursor and ask in plain English: *"open RDP into prod-bastion-01"*, *"rotate the Administrator password and update the bookmark"*, *"why is my tunnel stuck?"*.

### What you get

- **32 MCP tools** covering ADC auth, project/VM listing, saved connections, tunnels, SSH key install (Linux), Windows password rotation, Keychain, Windows App bookmarks, and FreeRDP launch.
- **3 MCP resources** for live state: `iap://connections`, `iap://tunnels`, and per-tunnel logs at `iap://tunnels/{id}/logs`.
- Shared `~/Library/Application Support/IAP Tunnel Manager/config.json` with the desktop app — favorites you create from Claude show up in the UI and vice versa.
- Tools are annotated with **read-only / destructive hints** so MCP-aware clients can require explicit approval for mutating actions (`windows_reset_password`, `connections_remove`, `auth_revoke`, …).

### Build and install the MCP server

```bash
go build -o /usr/local/bin/iap-mcp ./cmd/iap-mcp
```

(Requires the same `gcloud auth application-default login` already used by the desktop app.)

### Wire into Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "iap-tunnel-manager": {
      "command": "/usr/local/bin/iap-mcp"
    }
  }
}
```

Restart Claude Desktop. The tools appear under the plug icon.

### Wire into Cursor

Edit `~/.cursor/mcp.json` (or per-project `.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "iap-tunnel-manager": {
      "command": "/usr/local/bin/iap-mcp"
    }
  }
}
```

### Install the Skills bundle

Skills (`skills/*/SKILL.md`) teach Claude **when and how** to use the tools. They're loaded only when the user's intent matches a skill's `description`, so they're cheap.

```bash
mkdir -p ~/.claude/skills
cp -r skills/* ~/.claude/skills/
```

Bundled skills:

| Skill | Use when |
|-------|----------|
| `connect-windows-vm` | User wants to RDP into a Windows GCE VM |
| `connect-linux-vm` | User wants an SSH session to a Linux GCE VM |
| `rotate-windows-credentials` | User explicitly asks to rotate a Windows password |
| `debug-tunnel` | User reports a broken / hanging tunnel |
| `onboard-new-vm` | User wants to add new GCE VMs as saved connections |

For Cursor, copy the same files into `.cursor/skills/` (or `~/.cursor/skills/`).

### Try it

```
You:    What VMs do I have in my dev project?
Claude: [calls projects_list, then vms_list]
        Found 7 VMs in `acme-dev`. 4 are running, 2 are Windows.
        Want me to start a tunnel to one?

You:    Open Windows App for prod-bastion-01.
Claude: [calls connections_list → tunnels_start_for_connection → freerdp_launch]
        Tunnel up on localhost:53301; FreeRDP launching now.
```

---

## Get started

### Installation

Download the latest release from the [Releases](https://github.com/kvysotskyi/go-iap-mac/releases) page.

The application is code-signed with an Apple Developer ID certificate and notarized by Apple, ensuring secure installation and execution on macOS. Simply download, open, and start using the app - no manual security approval required.

### Configure IAP in your project

#### 1. Install Google Cloud CLI

Install the [Google Cloud CLI](https://cloud.google.com/sdk/docs/install) for your platform. This is required for authentication.

#### 2. Authenticate with Google Cloud

This app uses Application Default Credentials (ADC). Authenticate with:

```bash
gcloud auth application-default login
```

#### 3. Required IAM Permissions

Your Google account needs the following permissions:

| Role | Purpose |
|------|---------|
| `roles/viewer` | List projects |
| `roles/compute.viewer` | List VM instances |
| `roles/iap.tunnelResourceAccessor` | Create IAP tunnels |

#### 4. Configure Firewall Rules

Ensure your VPC has a firewall rule allowing IAP traffic:

| Setting | Value |
|---------|-------|
| Source IP range | `35.235.240.0/20` |
| Target | VMs you want to connect to |
| Ports | `3389` (RDP) |

### Connect to a Windows VM

1. **Launch the app** - It will check for valid GCP credentials
2. **Click "+ New"** - Create a new connection
3. **Select a project** - Use the search box to filter projects
4. **Select a VM** - Choose the VM you want to connect to
5. **Save Connection** - Click "Save Connection" to save for quick access
6. **Start Tunnel** - Click "Start Tunnel" to create the IAP connection
7. **Connect via RDP** - Choose your preferred connection method:
   - **Connect with FreeRDP** - One-click connection using FreeRDP (requires FreeRDP installed)
   - **Open Windows App** - Launch Microsoft Windows App directly
   - **Copy Address** - Copy `localhost:<port>` for use with any RDP client

## Troubleshooting

### "Application Default Credentials not found"

Run `gcloud auth application-default login` and restart the app.

### "Permission denied" when listing projects

Ensure your account has the `roles/viewer` role at the organization or folder level.

### "Failed to dial IAP"

Check that:
- The VM is running
- You have `roles/iap.tunnelResourceAccessor` permission
- The firewall allows IAP traffic (35.235.240.0/20)

### Tunnel starts but RDP fails

- Verify the VM has RDP enabled (Windows) or xrdp installed (Linux)
- Check that port 3389 is listening on the VM

### FreeRDP connection fails

If FreeRDP fails to launch:

- **FreeRDP not found**: Install FreeRDP using `brew install freerdp`
- **Credentials missing**: Ensure you've saved the connection with credentials stored in Keychain
- **Tunnel not running**: Make sure the tunnel is started before connecting with FreeRDP
- **Check logs**: View the tunnel logs in the app for detailed error messages from FreeRDP

## FAQ

### Is there an official Google IAP Desktop for macOS?
No. Google provides IAP Desktop only for Windows. macOS users must use CLI or third-party tools.

### How can I use Google Cloud IAP on macOS?
You can use `gcloud iap tunnel` (CLI) or a native macOS client like go-iap-mac.

### Is this an IAP Desktop alternative for Mac?
Yes. This project provides a native macOS UI for managing IAP SSH/RDP connections.

### Does this replace gcloud?
No. It uses gcloud under the hood and simplifies daily usage.

---

## Development

### Requirements

- Go 1.21+
- Node.js 18+
- [Wails CLI v2](https://wails.io/)

### Install Wails CLI

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

### Run in Development Mode

```bash
wails dev
```

This starts the app with hot-reload for frontend changes.

### Build the Application

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

# Download Go dependencies
go mod tidy

# Build for macOS
wails build -platform darwin/universal
```

The built application will be in `build/bin/`.

### Build the MCP server

```bash
go build -o /usr/local/bin/iap-mcp ./cmd/iap-mcp
iap-mcp --help
```

To run it for debugging:

```bash
printf '%s\n%s\n%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | iap-mcp
```

### Project Structure

```
go-iap/
├── main.go               # Wails entry (embed frontend, Run, Bind)
├── cmd/iap-mcp/          # MCP stdio server binary (Claude integration)
├── internal/ui/          # Wails-bound App and orchestration (split .go files)
├── internal/mcpserver/   # MCP tool + resource registrations backed by ui.App
├── internal/             # appconfig, gcp, gcessh, iaptunnel, session, winapp, mackeychain
├── skills/               # Claude/Cursor SKILL.md bundles for end-user workflows
├── wails.json            # Wails configuration
├── go.mod                # Go dependencies
├── frontend/
│   ├── index.html        # Main HTML
│   ├── package.json      # Frontend dependencies
│   ├── vite.config.js    # Vite configuration
│   └── src/
│       ├── main.js       # Frontend JavaScript
│       └── style.css     # Styles
├── CLOUD.md              # Per-package map for AI agents (read first)
└── README.md
```

## Technical Details

### IAP Tunnel Implementation

This app uses the [cedws/iapc](https://github.com/cedws/iapc) library which implements the Google IAP SSH Relay v4 protocol. The tunnel:

1. Listens on a local port (127.0.0.1)
2. For each incoming connection, establishes an IAP WebSocket tunnel
3. Proxies data bidirectionally between local and remote endpoints

### API Usage

| API | Purpose |
|-----|---------|
| Resource Manager API | List accessible GCP projects |
| Compute Engine API | List VM instances (aggregated across all zones) |
| IAP TCP Forwarding | WebSocket-based tunnel protocol |

## License

MIT License

go-iap-mac

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README