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.

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

Start here

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

flowchart LR
    B["Grok Bot on Mac or iPhone"] -->|HTTPS and OAuth| T["Owner-run tunnel"]
    T --> G["Gateway<br>Always-on server"]
    R["rehearse: local check"] --> G
    G --> S["Simulated light"]
    G --> D["Linux / ESP32 gadgets"]

The gateway gives Grok Bot six tools:

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

Learn more

• First success and the simulator guide
• Keep the gateway running as a background service, and leave the Grok Bot route on.
• Track usage: calls by token, device, capability and day, and an opt-in usage hook.
• Local operation, architecture and protocol 0.1.0
• Demo without HTTP: uv run python -m grok_gadgets_gateway.demo (uses test-only controls)
• Shared docs and the website: hub repository and https://grokgadgets.org/

Community

Questions, build photos and ideas are welcome on r/GrokGadgets. 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.