HEXhand
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
What HEXhand is
HEXhand is a small program that runs on your machine and exposes your project folder to ChatGPT through the Model Context Protocol (MCP). ChatGPT can then read files, write files, search, run commands and check the output — on your disk, with your toolchain, in your folder.
Your files stay yours. Nothing is uploaded. HEXhand serves the folder to ChatGPT on request.
Your machine does the work. Builds, tests and scripts run locally, not in someone's cloud.
One file to install. A single binary. No Node, no Docker, no Rust toolchain.
No tunnel account, no relay, no quota. Other builds of this tool send your traffic through a third-party tunnel service and stop working when the free quota runs out. HEXhand serves on its own port and lets you put your own name and certificate in front — unlimited, and it cannot be metered.
Optional remote mode. Keep HEXhand running on a server and drive a folder on a different computer through a small connector (see Remote mode).
HEXhand is a rebranded distribution of CatDesk (MIT). See NOTICE for attribution and the exact list of changes.
Related MCP server: chatgpt-codex-tools-mcp
What it costs: nothing
There is no subscription, no seat count, no usage meter and no account with us.
Piece | Cost |
HEXhand itself | Free — MIT licence, source in this repo |
Prebuilt binaries | Free — Linux, macOS (Intel + Apple Silicon), Windows |
Caddy (HTTPS in front of it) | Free — open source |
DuckDNS (name for a changing home IP) | Free |
ChatGPT connector | Uses the plan you already pay for |
The only thing you provide is the machine it runs on — a spare PC, a NAS or a small VPS. That is the whole cost of ownership.
What you need
ChatGPT | A plan that allows custom connectors (Plus, Pro, Team or Enterprise) |
A folder | The project you want ChatGPT to work in |
A way to reach it | Optional. Run HEXhand on your own network and point Caddy at it — see Run it free on your own server. A free DuckDNS name is enough. No tunnel account, no relay service, no quota. |
Older CatDesk builds forced an ngrok account before they would start. HEXhand does not: with no token configured it starts in self-hosted mode and serves on its local port. A tunnel is opt-in (
tunnelEnabled = truein the config) for people who want a public URL without running a proxy.
Install
Grab the file for your platform from Releases and run it.
Linux
curl -L -o hexhand https://github.com/hexf1ow/HEXhand/releases/latest/download/hexhand-linux-x64
chmod +x hexhand
./hexhandmacOS (Apple Silicon shown; use hexhand-darwin-x64 on Intel)
curl -L -o hexhand https://github.com/hexf1ow/HEXhand/releases/latest/download/hexhand-darwin-arm64
chmod +x hexhand
xattr -d com.apple.quarantine hexhand 2>/dev/null # clears the "unverified developer" flag
./hexhandWindows
Download hexhand-win32-x64.exe from
Releases and double-click it, or run it from a
terminal:
.\hexhand-win32-x64.exeWindows SmartScreen will warn you the first time because the binary is not code-signed. Choose More info → Run anyway.
Verify a download against the published checksums: sha256sum -c SHA256SUMS (Linux/macOS) or
Get-FileHash (Windows). SHA256SUMS is attached to every release.
First run — five minutes
Start HEXhand in the folder you want ChatGPT to work in:
cd ~/projects/my-app hexhandPick a mode — Control Computer is the usual choice. That is the whole onboarding: no account, no token, no sign-up.
Copy the MCP URL it shows, e.g.
http://127.0.0.1:3200/AbCdEf1234567890/mcpThe
<slug>is a random 16-character identifier generated for you. It is the only credential — treat the URL like a password.That URL is local. To reach it from ChatGPT, put a reverse proxy in front (next section) or turn on the optional tunnel.
Add it to ChatGPT: Settings → Connectors → Add custom connector, paste the URL, save. (On some plans this appears as Developer mode → Add connector.)
Test it. Ask ChatGPT: "List the files in this project and tell me what it does."
What ChatGPT can do with it
Tool | What it does |
| Run a shell command in the folder and return the output |
| Start a long-running command in the background |
| Read more output from a background command |
| Stop a background command |
| Read one or more files |
| Create or overwrite a file |
| Replace an exact snippet inside a file |
| Search text across the folder |
| Delete a file or folder |
| Ask for the rules of the current workspace |
Working-folder rules are enforced: any path outside the folder HEXhand was started in is refused.
Remote mode
Run HEXhand on a server and let it drive a folder on another machine — a build box, a Windows desktop, a lab machine you don't want to install on.
Where the folder lives | How it works |
Same machine as HEXhand | Run the binary in the folder. Nothing else needed. |
Another Windows machine |
|
Another Linux / macOS machine | Run the binary there, or use the connector script — see connectors |
On the machine that holds the files, start the connector inside that folder:
powershell -ExecutionPolicy Bypass -File hexhand-here.ps1 -Path "D:\work\site"It listens on port 3210, accepts only requests with the shared bearer token, and refuses any path outside the folder it was started in.
On the server, point HEXhand at it:
CATDESK_REMOTE_URL=http://<connector-host>:3210/ \
CATDESK_REMOTE_TOKEN=<shared token> \
hexhandEvery tool call is then forwarded to the connector, so the files ChatGPT edits live on the other machine. The variable names keep their original spelling so existing CatDesk connectors keep working.
Run it free on your own server
The whole stack is free: HEXhand in Docker, Caddy for HTTPS, DuckDNS for a name when your home IP changes. Nothing here needs a paid service or an account with us.
Internet ──► DuckDNS name ──► Caddy (HTTPS) ──► HEXhand container ──► connector ──► your folder1. Get a name for your IP — sign in at duckdns.org, create a subdomain, and keep it pointed at your connection with their updater container:
docker run -d --name duckdns --restart=unless-stopped \
-e SUBDOMAINS=yourname -e TOKEN=<duckdns-token> -e LOG_FILE=false \
linuxserver/duckdns2. Start HEXhand with limits — the limits are what stop a runaway command from eating the machine:
docker build -t hexhand .
docker run -d --name hexhand --restart=unless-stopped \
--memory 1g --memory-swap 1g --cpus 1.5 --pids-limit 512 \
-v "$HOME/.hexhand:/root/.hexhand" \
hexhand3. Put Caddy in front so it gets a real certificate (Caddyfile):
yourname.duckdns.org {
reverse_proxy hexhand:3201
}Open ports 80/443 to Caddy only. The HEXhand port itself stays on the Docker network.
4. Add the URL in ChatGPT — https://yourname.duckdns.org/<slug>/mcp.
Video walkthroughs of DuckDNS (watch one, the rest is copy-paste):
Techno Tim — Self-Host All Your Homelab Services with DuckDNS — https://www.youtube.com/watch?v=bVmUV1G5wpI
Awesome Open Source — DuckDNS for Routing Internet Traffic to your Home Lab — https://www.youtube.com/watch?v=Dm5MyuUdq2s
Why run it in a container
A container does not make an agent safe on its own — what makes it safe is the boundary you put around it:
cgroup limits (
--memory,--cpus,--pids-limit) stop a runaway build or a fork bomb from taking the host down; the kernel refuses the allocation instead of the machine swapping to death.restart policy (
--restart=unless-stopped) brings it back by itself after a crash or a reboot.folder guard in the app and the connector — every path is checked, so it cannot wander outside the one folder you pointed it at.
no host filesystem beyond the single volume you mount, and no privileged mode.
That is the combination worth advertising: bounded CPU, bounded memory, bounded files, restarts by itself.
Connector icon (ChatGPT)
ChatGPT shows the connector icon very small, so the artwork is supplied in the sizes it actually renders from — square, transparent, tightly cropped:
File | Size | Use |
| 512×512 | connector icon (recommended upload) |
| 256×256 | stores that ask for smaller |
| 128×128 | minimum size |
| 16–256 | Windows executable icon |
In ChatGPT: Settings → Connectors → your HEXhand connector → Edit → icon → upload the 512px file.
Configuration
Settings live in ~/.hexhand/config.toml (Windows: %USERPROFILE%\.hexhand\config.toml).
If you used CatDesk before, an existing ~/.catdesk folder is carried over automatically on first
start — you keep your slug and settings.
Troubleshooting
Symptom | Fix |
| Another HEXhand/CatDesk instance is already running. Close it, or let HEXhand pick the next port. |
ChatGPT says the connector failed | Open the MCP URL in a browser — you should get a JSON-RPC error, not a connection failure. If the connector is remote, check it is running there and the token matches. |
ChatGPT cannot reach the URL | A local URL is not reachable from outside. Put Caddy in front with a real hostname (see the deployment section), or enable the optional tunnel. |
A command runs forever | Ask ChatGPT to use |
ChatGPT card: "software did not initiate" / instruction timeout | Fixed in 0.11.2: the first tool call runs immediately instead of asking for a second round trip. Update the binary, or call |
Windows: "HEXhand here" does nothing | Run |
Windows: "unverified publisher" | Expected — the binary is not code-signed. More info → Run anyway. |
Build from source
git clone https://github.com/hexf1ow/HEXhand.git
cd HEXhand
cargo build --release # -> target/release/hexhandRust 1.85+ (edition 2024). The release profile uses LTO and strips symbols. Container builds are
supported too — see deploy/Dockerfile and deploy/entrypoint.sh.
Security notes
The
<slug>in the URL is the only thing protecting your workspace. Anyone with the URL can use every tool. Rotate it by onboarding again if it leaks.HEXhand serves one folder: the one it was started in. Paths outside it are rejected.
The tunnel is outbound from your machine; you never open a port on your router.
Troubleshooting the ChatGPT app
If the app shows "Couldn't open Get usage instructions" or "Get usage instructions timed out", the connector never finished registering — almost always one of these:
The server refused
initialize. The app opens a session before listing tools and gives up when it is refused, which leaves every tool panel timing out. HEXhand answersinitializefrom 0.11.14; on anything older, upgrade the server.A stale plugin record. Remove the plugin, quit the app fully (not just close to tray), then add the MCP server again with
https://<your-host>/agent/<slug>/mcp.Wrong URL. It must end in
/mcp. A missing/mcpreturns 404 for every call.Authentication. HEXhand has no auth of its own: choose No authentication, and tick I understand and want to continue on the risk screen.
Check the server side first — a healthy connector answers this in under a second:
curl -s -X POST https://<your-host>/agent/<slug>/mcp \
-H 'Content-Type: application/json' -H 'MCP-Protocol-Version: 2026-07-28' -H 'Mcp-Method: initialize' \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2026-07-28","capabilities":{}}}'A 200 with serverInfo means the server is fine and the problem is the stored plugin in the app.
Working folder
The connector starts with Windows and stays connected, so nothing needs activating. It serves the folder it was last started in and remembers it between reboots; right-click a folder and choose HexHand Here to switch. Paths outside that folder are rejected.
Licence and attribution
MIT — see LICENSE.
HEXhand is a rebranded distribution of CatDesk, copyright (c) 2026 xeift.eth, also MIT. Upstream documentation is kept in docs/CATDESK-UPSTREAM-README.md. HEXhand is not affiliated with or endorsed by the CatDesk authors.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Connect ChatGPT and Claude to your Mac, Windows or Linux with secure MCP remote access.
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Related MCP Servers
- AlicenseNot gradedqualityAmaintenanceA desktop launcher and local MCP workspace server that enables ChatGPT and other MCP clients to securely read, edit, search, run commands, and show changes in selected local project folders.1MIT
- AlicenseNot gradedqualityBmaintenanceEnables ChatGPT to inspect and edit local projects through a secure MCP interface, offering workspace management, file operations, git integration, and safe command execution.6MIT
- FlicenseNot gradedqualityCmaintenanceA local MCP runtime for macOS and Windows that enables ChatGPT to read, edit, search, run tests, and capture screenshots in your local project folder while keeping your source code on your machine.164-
- AlicenseAqualityBmaintenanceConnects ChatGPT to a local developer workspace through MCP, enabling bounded repository analysis, file and image inspection, direct edits, command verification, and Git-aware review.22MIT