GPG Bridge

Bridge GPG operations from Linux remotes (WSL, Dev Containers, SSH) to the GPG agent on your local host running GnuPG 2.1+. Sign commits, verify signatures, and encrypt/decrypt files from any remote environment — no extra configuration needed on the remote side.

This is an extension pack that installs two cooperating components:

• GPG Bridge Agent (hidale.gpg-bridge-agent) — runs on your local host, connects to the local GPG agent
• GPG Bridge Request (hidale.gpg-bridge-request) — runs in each remote environment, presents a standard GPG agent socket

Requirements

Installation

Search for GPG Bridge in the VS Code Extensions sidebar, or install from the marketplace page. Both component extensions install automatically.

Both extensions start automatically when VS Code opens — no manual start needed.

How It Works

1. Request extension queries gpg's standard socket location with gpgconf
2. Request creates the standard socket to listen for remote client gpg commands
3. Agent extension queries gpg's "extra" restricted socket location with gpgconf
4. Agent authenticates with gpg-agent and validates its connectivity
5. Remote client starts a session by opening a connection to the standard socket
6. Client sends gpg commands to the standard socket
7. Request bridges commands over VS Code's built-in command tunnel to the Agent
8. Agent authenticates and forwards the commands to the host gpg-agent
9. gpg-agent replies, Agent replies, and Request replies back to the remote client
10. Client completes, or an error along the path closes the session
    

Configuration

{
  // example
  "gpgBridgeAgent.gpgBinDir": "C:\\Program Files\\GnuPG\\bin",
  "gpgBridgeAgent.debugLogging": false,
  "gpgBridgeRequest.gpgBinDir": "/usr/bin",
  "gpgBridgeRequest.autoSyncPublicKeys": "pairs",
  "gpgBridgeRequest.debugLogging": false,
}

Commands

Both extensions start automatically. These commands are available via the Command Palette (Ctrl+Shift+P) if you need to manually control them:

Typical Workflow

1. Open VS Code on your local host — GPG Bridge Agent starts automatically
2. Open a WSL / Dev Container / SSH remote — GPG Bridge Request starts automatically
3. GPG operations in the remote now use your local host's keys. Existing apps and tools need no reconfiguration.

To verify it is working, run in a remote terminal:

gpg --list-keys      # should list your local host's keyring
git commit -S -m "test"   # signed commit should succeed

Architecture

This project uses a three-part monorepo:

gpg-bridge-agent/    agent bridge (local host UI context)
gpg-bridge-request/  request bridge (remote workspace context)
pack/                extension pack manifest (no code)
shared/              shared protocol utilities (@gpg-bridge/shared)

A three-extension architecture is necessary because a single multi-context extension cannot reliably auto-activate in all remote scenarios. The agent must run in the local host UI context; the request must run in the remote workspace context. The pack bundles both so users install one item.

For detailed protocol and state machine documentation see:

• gpg-bridge-agent/README.md
• gpg-bridge-request/README.md
• docs/gpg-agent-protocol.md

Contributing

See CONTRIBUTING.md for dev setup, build, test, and commit guidelines.