gcloud-proxy-manager

A lightweight desktop GUI for managing Google Cloud SQL Auth Proxy tunnels. Select an instance from a dropdown, hit Start, and the app runs cloud-sql-proxy in the background while streaming its output to a built-in log view.

Fair warning — This project is mostly vibe-coded and exists to scratch a personal itch. It does the job for me, but don't expect polished docs, extensive test coverage, or timely issue responses. PRs are welcome, but support will be minimal.

Features

• Configure multiple Cloud SQL instances in a single TOML file
• One-click start/stop of cloud-sql-proxy tunnels
• Real-time log output in the GUI
• Cross-platform (Linux, macOS, Windows) via Fyne

Prerequisites

Dependency	Notes
Go 1.26+	Required to build from source
C compiler	Fyne uses CGO for its OpenGL/GLFW driver
System graphics libs	See Fyne prerequisites for your OS
cloud-sql-proxy	Must be installed and on PATH, or pointed to via CLOUD_SQL_PROXY env var
GCP credentials	Application Default Credentials or a service account key — handled by cloud-sql-proxy itself

System libraries (Linux)

On Debian/Ubuntu:

sudo apt-get install gcc libgl1-mesa-dev xorg-dev

On Fedora:

sudo dnf install gcc mesa-libGL-devel libXcursor-devel libXrandr-devel libXinerama-devel libXi-devel libXxf86vm-devel

Build

git clone https://github.com/<your-user>/gcloud-proxy-manager.git
cd gcloud-proxy-manager
go build -o gcloud-proxy-manager .

Or run directly:

go run .

Taskfile

If you use Task, common targets are:

Task	What it does
task / task default	Runs build then package (one-shot .deb build)
task build	go build -o gcloudproxymanager main.go
task build-linux	Same as build (Linux binary in the repo root)
task package	Runs nfpm to produce a .deb (expects gcloudproxymanager in the repo root — use task or task build first)

Install Task for your OS, then from the repo root: task for a full build+package, or task build / task package individually.

Debian package (nfpm)

The nfpm config lives in nfpm.yaml. It packages the gcloudproxymanager binary and the desktop entry under packaging/.

1. Install nfpm (see nfpm installation).

2. Build the Linux binary at the repo root (same name nfpm expects), then create the package:

   task

   Or step by step: task build then nfpm package --packager deb / task package. Without Task: go build -o gcloudproxymanager main.go then nfpm package --packager deb.

By default the .deb is written in the current directory, named like gcloud-proxy-manager_<version>_<arch>.deb per nfpm.yaml. Install with sudo dpkg -i gcloud-proxy-manager_*.deb. Bump version and other metadata in nfpm.yaml when cutting a release.

Configuration

The app reads proxy definitions from a TOML file. By default it uses $XDG_CONFIG_HOME/gcloud-proxy-manager/config.toml (on most Linux systems that is ~/.config/gcloud-proxy-manager/config.toml). Override the path with the GCLOUD_PROXY_MANAGER_CONFIG environment variable.

If no config file exists on first run, the directory and a commented template file are created automatically.

Use the text-file icon beside the connection form to open the TOML in your default editor (via the OS). If the file location differs between a terminal and the GNOME app menu, your shell probably sets XDG_CONFIG_HOME or GCLOUD_PROXY_MANAGER_CONFIG only in .zshrc / .bashrc (interactive shells). Graphical launches do not load those files, so the app falls back to ~/.config/.... Put the same exports in ~/.profile, use Environment= in your .desktop file, or configure a session-wide environment in GNOME if you need one path everywhere.

Example config.toml

[[proxies]]
instance   = "my-app-db"
local_port = 3306
connection = "my-project:us-central1:my-instance"

[[proxies]]
instance   = "analytics-db"
local_port = 3307
connection = "my-project:europe-west1:analytics"

Field	Description
instance	A friendly name shown in the GUI dropdown
local_port	Local TCP port the proxy listens on (1–65535)
connection	Cloud SQL instance connection name (PROJECT:REGION:INSTANCE)

Usage

1. Create or edit the config file (default path above) with your proxy definitions.
2. Run the app — a window appears with a dropdown of configured instances.
3. Select an instance, adjust the port if needed, and click Start Proxy.
4. Logs from cloud-sql-proxy stream into the text area in real time.
5. Click Stop to send SIGTERM (or kill on Windows) to the proxy process.

Environment variables

Variable	Default	Purpose
GCLOUD_PROXY_MANAGER_CONFIG	(see above)	Path to the TOML configuration file
CLOUD_SQL_PROXY	cloud-sql-proxy	Path to the Cloud SQL Auth Proxy binary

Project structure

├── main.go                          # Entry point
├── Taskfile.yml                     # Task runner (build, package)
├── nfpm.yaml                        # Debian package metadata (nfpm)
├── packaging/
│   └── gcloud-proxy-manager.desktop # Installed by the .deb for app menus
├── internal/
│   ├── config/config.go             # Config loading and validation
│   ├── gui/gui.go                   # Fyne-based GUI
│   └── commands/cloud_auth_proxy.go # Process management for cloud-sql-proxy
├── go.mod
└── go.sum

License

This project is licensed under the MIT License.