Made by @adidshaft ↗

Grok Bot is made by SpaceXSI.
Grok Gadgets is an independent project.

↗

Grok Gadgets gateway

The connection point between your Grok Bot and your gadgets: a built-in simulated light, Linux gadgets and ESP32 devices. It serves six MCP tools. The owner tested USB and Wi-Fi hardware through the gateway. Grok Bot calls the six tools natively from the Mac and iPhone apps through serve --oauth behind a tunnel you run (record, project status). Independent project, not affiliated with SpaceXSI.

On this page

Writing style: ASD-STE100-inspired English. Use short sentences, active verbs and one instruction per step. This is not certified compliance.

Start here

Path Next step
Use a gadget Connect Grok Bot to the tested kit
Build a gadget Start with a simulated light
Run the gateway Keep a local gateway available

Install from PyPI

The package is on PyPI. Install it into a virtual environment with Python 3.11+. It is an alpha, so name the version or pass --pre:

python3 -m venv .venv
.venv/bin/python -m pip install --pre grok-gadgets-gateway
.venv/bin/grok-gadgets-gateway --version

Each GitHub release also has the wheel and SHA256SUMS; the PyPI files are the same build.

On an Intel Mac, cryptography has no prebuilt wheel and needs a Rust toolchain to build.

For your first simulator test, follow first success.

Quick start

For contributors: clone the source with Git and uv.

git clone https://github.com/adidshaft/grok-gadgets-gateway.git
cd grok-gadgets-gateway
uv sync --locked
uv run grok-gadgets-gateway init
uv run grok-gadgets-gateway serve --simulator
uv run grok-gadgets-gateway rehearse

Run rehearse in a second terminal while serve keeps running. It calls the six tools in the order Grok Bot will: list the gadgets, set the simulated light blue, read its state. See first success in five minutes.

How it works

Connection diagramGrok Bot on Mac or iPhone to Owner-run tunnel: HTTPS and OAuth; Owner-run tunnel to Gateway Always-on server; rehearse: local check to Gateway Always-on server; Gateway Always-on server to Simulated light; Gateway Always-on server to Linux / ESP32 gadgetsHTTPS and OAuthGrok Bot on Mac or iPhonerehearse: local checkOwner-run tunnelGateway Always-on serverSimulated lightLinux / ESP32 gadgets
Grok Bot on Mac or iPhone to Owner-run tunnel: HTTPS and OAuth; Owner-run tunnel to Gateway Always-on server; rehearse: local check to Gateway Always-on server; Gateway Always-on server to Simulated light; Gateway Always-on server to Linux / ESP32 gadgets. Intended paths; verification gates apply.

The gateway gives Grok Bot six tools:

Tool What it does
gadgets_list_devices Lists gadgets, their commands and what each one does. Call it first.
gadgets_get_state Reads a gadget's last reported state and how fresh it is.
gadgets_command Sends a command and waits up to 3 seconds for the result.
gadgets_command_status Reads the result of a slower command later.
gadgets_read_events Reads button presses and other events in order.
gadgets_diagnostics A support report with no tokens, state or arguments.

A relay in accounts mode (serve --oauth --accounts) scopes every tool to the caller's own gadgets. It adds gadgets_claim, gadgets_remove, gadgets_share and gadgets_name. With gadgets_name you can say "the desk display" instead of an ID (relay host guide).

A result is the gadget's own report, not proof of a physical effect.

Connect a gadget

init prints two settings blocks with absolute paths. Use the first when the connector starts the gateway itself (stdio). Use the second for a running serve at http://127.0.0.1:8766/mcp, with the bearer token from ~/.config/grok-gadgets/mcp-token. init --client http prints just one.

Gadgets connect to 127.0.0.1:8765 with their own token:

uv run grok-gadgets-gateway enroll desk-lamp --token-file desk-lamp.token

enroll desk-lamp --rotate issues a new token for the same gadget. Write gadgets with the Linux SDK or the ESP32 SDK; the Linux SDK's dev command needs no token at all. Both ports are loopback only. A Wi-Fi gadget on your home network can use the opt-in TLS listener on one private address, serve --lan-listen; see Wi-Fi devices.

Grok Bot today

The owner tested Grok Bot local commands on 12 October 2026. Grok Bot ran rehearse on the Mac. Read the connection evidence. On 13 October 2026 Grok Bot also called the six tools natively from the Mac and the iPhone. It used an owner-run tunnel and serve --oauth, a sign-in that you approve on the Mac (tunnel guide). The owner tested this route for one day, including a phone call over cellular. The original Mac route needs an awake Mac. During its sleep check, calls failed; nothing was queued. An always-on relay now lets the kit work without the Mac. See the relay record. Phone setup passed on iPhone and Android; Grok Bot calls from Android remain untested. See the phone setup record and roadmap. Never expose port 8765. Read remote access and security first.

Troubleshooting

Symptom Next step
Not sure which command Run grok-gadgets-gateway --help. Use serve for a long-running process; stdio is for a connector that starts the gateway itself.
No simulated light Start with --simulator.
401 from rehearse Send Authorization: Bearer <token> with the exact contents of the token file.
Config rejected Use strict v1 JSON within the documented bounds.
Command still accepted or dispatched The gadget is slow. Poll gadgets_command_status; never resend with a new command ID.

Learn more

Community

Questions, build photos and ideas are welcome on Grok Gadgets community on X. Report bugs and request features in GitHub Issues. New here? Pick a good first issue and read CONTRIBUTING. Get help: SUPPORT. Contribute on the dev branch; main holds tagged stable releases (branches).

License and affiliation

Apache-2.0; see LICENSE and NOTICE. Grok Gadgets is an independent open-source project. It is not affiliated with, endorsed by or sponsored by SpaceXSI. We reconstructed the pre-publication commit dates; see the history record.

Project discussion

Ask questions and share gadget ideas in hub Discussions. Use this repository's issue forms for defects.

Source: grok-gadgets-gateway/README.md