greyhack-bridge

A bridge that lets you drive Grey Hack from your host machine — push MiniScript source, run compiled tools, read/send mail, and run parallel in-game sessions from a Bash CLI.

Architecture

gh.sh / greyhack_bridge.py   ←→   HermesGHRaw (BepInEx plugin, port 7778)   ←→   Grey Hack game

• greyhack_bridge.py — Python bridge (push files, run tools, read mail)
• gh.sh — Bash CLI wrapping the bridge with tool-specific helpers
• HermesGHRaw/ — C# BepInEx plugin that listens on TCP 7778, runs commands on real in-game terminals, and captures output via Harmony patches on Terminal.AddTexto
• tools/*.src — MiniScript in-game CLIs deployed with ./gh.sh --deploy
• mailread.src — in-game mail client (also deployed by --deploy)

Requirements

• Grey Hack (Steam)
• BepInEx 5 installed in the Grey Hack folder
• GreyHackMessageHook5.dll in BepInEx/plugins/
• HermesGHRaw.dll built and copied to BepInEx/plugins/ (see below)
• Python 3.x
• Node.js + npm install -g greybel-js

Setup

1. Build the plugin

cd HermesGHRaw/HermesGHRaw
dotnet build -c Debug
# Copy the output to Grey Hack's BepInEx plugins folder:
cp bin/Debug/netstandard2.1/HermesGHRaw.dll \
   "$STEAM/steamapps/common/Grey Hack/BepInEx/plugins/"

The .csproj references game DLLs at the default Steam path (C:\Program Files (x86)\Steam\...). Adjust HintPath entries if your install is elsewhere. The game must be closed while copying the DLL (Windows locks loaded assemblies).

Verify the plugin loaded: check BepInEx/LogOutput.log for Patched Terminal.AddTexto and :7778.

2. Configure mail credentials

Copy gh.conf.example to gh.conf (gitignored) and fill in your in-game email credentials:

MAIL_USER="you@yourdomain.gh"
MAIL_PASS="yourpassword"
DIR=/home/yourname/hermes       # override default in-game working dir

Or edit gh.sh directly and set MAIL_USER / MAIL_PASS / DIR.

3. Install Python deps + greybel

npm install          # installs greyhack-message-hook-client
npm install -g greybel-js

4. Deploy in-game tools

Start Grey Hack, open at least one terminal on your local machine, then:

./gh.sh --deploy

This pushes and compiles every tools/*.src and mailread.src into the game.

Usage

# List open in-game terminals
./gh.sh terminals

# Run a tool
./gh.sh sysinfo
./gh.sh fs ls /home
./gh.sh ps list
./gh.sh netscan 1.2.3.4
./gh.sh netscan lan
./gh.sh crack <hash>

# Exploit
./gh.sh exploit scan <ip> <port>
./gh.sh exploit shell <ip> [port]

# Mail
./gh.sh mailread list
./gh.sh mailread read <id|index>
./gh.sh mailread reply <id|index> "your reply body"

# Target a specific terminal (for parallel work)
./gh.sh -t 1 netscan 5.6.7.8
./gh.sh par "netscan 1.2.3.4" "netscan 5.6.7.8"

# Extend timeout for slow ops
./gh.sh --timeout 120000 crack <hash>

How MP execution works

Scripts run on a real in-game terminal window (a registered Ventana with a valid PID). The plugin finds terminals via FindObjectsOfType<Terminal>, picks one, calls Terminal.LaunchCommand(string) (types and runs the command like a human), and captures output via a Harmony postfix on Terminal.AddTexto. InternalBash (PID -10) is a dead end in MP — its AddTexto override is empty and GetVentana(-10) returns null.

You must have at least one terminal open in-game on your local machine before calling any tool. Auto-spawn is not possible (Grey Hack opens terminals through a pooled UI with no headless entry point).

Notes

• Running scripts consumes the in-game machine's RAM — heavy scripts can OOM (a game limit, not a bridge bug)
• From Git Bash, POSIX path conversion is suppressed via MSYS_NO_PATHCONV=1 MSYS2_ARG_CONV_EXCL='*' in gh.sh
• scratch/ contains experimental / one-off scripts used during development

License

MIT