GATEKEEPER SHELL DOCS

Introduction

Traditional pair programming tools like SSH or Tmux sharing require setting up public keys, configuring firewalls, and ultimately giving a remote user unrestricted access to your entire operating system.

Gatekeeper Shell flips the script. It uses a zero-trust proxy architecture. The guest does not interact with your OS directly. Instead, they interact with a WebSocket server, which queues commands for the host to review and approve.

Installation

If you have Node.js installed, you don't even need to install Gatekeeper Shell permanently. You can run it on-demand using npx.

# Start a new session instantly
npx gatekeeper-shell

Alternatively, if you downloaded the standalone .exe or binary from our homepage, just execute it directly in your terminal:

./gatekeeper

Connecting

When a host starts a session, they are provided with a unique relay URL. They share this URL with the guest.

The guest connects by passing the URL as an argument to the CLI:

# Connect as a guest
npx gatekeeper-shell https://relay.vishalraut.me/YOUR_CODE

The host will receive a notification that a guest has joined, and the guest can immediately begin typing commands.

Security Model

The core of Gatekeeper is built on absolute paranoia. By default, nothing executes without explicit permission.

When a guest types a command, it is transmitted via Secure WebSockets (WSS) to the relay server, which routes it to the host. The host's CLI intercepts the string, pauses the background shell, and renders an interactive prompt.

Host Approval

Every single command sent by a guest triggers a Y/n prompt on the host's terminal.

Guest ➜ ls -la
Approve? [Y/n]: y

Pressing Enter or typing y executes the command and streams the stdout/stderr back to the guest. Typing n blocks the command instantly.

Dangerous Commands

Gatekeeper includes a Safe Rules Engine. If a guest attempts to run a known destructive command (e.g., rm, sudo, mkfs, format), the host is alerted with a glaring red warning before the approval prompt.

Guest ➜ rm -rf /
WARNING: DANGEROUS COMMAND DETECTED 
Approve? [Y/n]:

P2P Relay

Because most developers sit behind NATs or corporate firewalls, Gatekeeper utilizes a central WebSocket relay server. This relay is dumb and stateless. It merely passes encrypted string buffers between Client A (Host) and Client B (Guest).

No shell state, history, or output is stored on the relay server.

CLI Flags

Gatekeeper Shell supports a number of command-line flags for advanced configuration:

Encryption

All traffic between the host and guest is transmitted over WSS (WebSocket Secure), which provides TLS 1.3 encryption at the transport layer. No plain text is ever exposed on the wire.

The relay server acts as a blind passthrough — it cannot inspect the contents of the messages it routes. Shell output, command strings, and session metadata are all opaque to the relay.

Host ──[TLS/WSS]──▶ Relay Server ──[TLS/WSS]──▶ Guest
         (encrypted)                    (encrypted)
              ↕ Command approval happens locally on host

For end-to-end encrypted deployments, you can self-host the relay on your private network and use mutual TLS certificates.

Session Logs

By default, all commands executed during a Gatekeeper session are logged locally on the host machine to ~/.gatekeeper/sessions/. Each session creates a new log file with the session ID and timestamp.

Log files include:

• Timestamp of each command request
• Whether the host approved or rejected
• The full command string (not the output)
• Guest's relay-assigned identifier

# Example log entry
[2026-06-30T14:22:10Z] GUEST_COMMAND: "ls -la"
[2026-06-30T14:22:11Z] HOST_ACTION: APPROVED
[2026-06-30T14:22:13Z] GUEST_COMMAND: "rm -rf /tmp/old"
[2026-06-30T14:22:14Z] HOST_ACTION: REJECTED (dangerous pattern)

To disable logging, run with -log="". To write logs to a custom path, use -log=/path/to/file.log.

Advanced Usage

Behind the scenes, Gatekeeper utilizes standard os/exec pipes to maintain a persistent background shell (like PowerShell on Windows, or Bash on Linux). This means directory changes (cd) and environment variable exports persist across commands, unlike a standard SSH command execution.

You can also pipe a session ID directly to the CLI for scripting:

# Use a specific session relay URL
npx gatekeeper-shell -server wss://relay.vishalraut.me/ws?session=MY_ID

Self Hosting

For ultimate privacy (e.g., within a corporate intranet), you can host the Go relay server yourself.

# 1. Clone the repository
git clone https://github.com/VishalRaut2106/go-gatekeeper.git

# 2. Run the server
cd go-gatekeeper
go run ./cmd/server

Then, tell your CLI to use your custom server:

npx gatekeeper-shell -server ws://localhost:8080/ws?role=host

Environment Variables

You can configure the CLI and Server using the following environment variables:

• GATEKEEPER_RELAY_URL — Overrides the default public relay URL.
• PORT — (Server-only) Defines which port the Go WebSocket server listens on. Default: 8080.
• GATEKEEPER_LOG_DIR — Override the directory where session logs are written.
• GATEKEEPER_NO_APPROVE — Set to 1 to globally disable approval prompts.

Troubleshooting

Connection refused / WebSocket error

This usually means the relay server is unreachable. Check your internet connection. If self-hosting, confirm the Go server is running and the port is open.

Guest commands not executing

Make sure you're running Gatekeeper Shell as the host, not as a guest. The host terminal is the one that will display approval prompts.

npm / npx version errors

Gatekeeper Shell requires Node.js v18+. Run node --version to verify your version. If outdated, use nvm to upgrade.

Windows PowerShell — execution policy error

Run PowerShell as Administrator and execute: Set-ExecutionPolicy RemoteSigned before running the binary.

Changelog