Go Iap Mac
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.
Ask AI about Go Iap Mac
Powered by Claude Β· Grounded in docs
I know everything about Go Iap Mac. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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.

Access Windows VMs from anywhere
IAP Tunnel Manager uses Identity-Aware Proxy (IAP) 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 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:
- Start the tunnel - Click "Start Tunnel" to establish the IAP connection
- 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:
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 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 atiap://tunnels/{id}/logs. - Shared
~/Library/Application Support/IAP Tunnel Manager/config.jsonwith 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
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:
{
"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):
{
"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.
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 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 for your platform. This is required for authentication.
2. Authenticate with Google Cloud
This app uses Application Default Credentials (ADC). Authenticate with:
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
- Launch the app - It will check for valid GCP credentials
- Click "+ New" - Create a new connection
- Select a project - Use the search box to filter projects
- Select a VM - Choose the VM you want to connect to
- Save Connection - Click "Save Connection" to save for quick access
- Start Tunnel - Click "Start Tunnel" to create the IAP connection
- 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.tunnelResourceAccessorpermission - 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
Install Wails CLI
go install github.com/wailsapp/wails/v2/cmd/wails@latest
Run in Development Mode
wails dev
This starts the app with hot-reload for frontend changes.
Build the Application
# 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
go build -o /usr/local/bin/iap-mcp ./cmd/iap-mcp
iap-mcp --help
To run it for debugging:
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 library which implements the Google IAP SSH Relay v4 protocol. The tunnel:
- Listens on a local port (127.0.0.1)
- For each incoming connection, establishes an IAP WebSocket tunnel
- 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
