Grok Gadgets Linux SDK

Turn Python functions into gadgets your Grok Bot can call through the Grok Gadgets gateway. Start with a software lamp; add your hardware code later. This SDK does not yet have accepted Linux hardware evidence. The owner verified native Grok Bot calls from Mac and iPhone through gateway OAuth and an HTTPS tunnel. See the 13 October record. That result used the separate ESP32 kit; it does not verify Linux hardware (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 SDK 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-linux-sdk[gateway]"
.venv/bin/grok-linux-agent --version

The gateway extra adds the gateway for grok-linux-agent dev. Each GitHub release also has the wheel and SHA256SUMS.

Quickstart

For contributors: clone the source with Git and uv.

git clone https://github.com/adidshaft/grok-gadgets-linux-sdk.git
cd grok-gadgets-linux-sdk
uv sync --extra gateway

Save this as my_gadget.py:

from grok_gadgets_linux import Gadget

lamp = Gadget("desk-lamp", "Desk lamp", state={"on": False})


@lamp.command("Turn the desk lamp on or off")
def set_light(on: bool) -> dict:
    # Your hardware code goes here, for example gpio.write(17, on).
    return {"on": on}

Run it:

uv run grok-linux-agent dev ./my_gadget.py

dev starts a local gateway, connects your gadget with no token to copy, and prints the local test settings. Grok Bot uses a separate OAuth connection. Run the local rehearsal:

uv run grok-gadgets-gateway rehearse --device desk-lamp --command set.light --args '{"on": true}'

How it works

flowchart LR
    A["Your Python functions"] --> S["SDK agent"]
    S <-->|"127.0.0.1:8765"| G["Gateway"]
    B["Grok Bot"] -->|"HTTPS and OAuth via owner-run tunnel"| G
    R["rehearse (local check)"] --> G

Your file declares a Gadget and its commands. The agent connects it to the gateway on the same computer, and the gateway offers its commands to Grok Bot, with your one-line descriptions. dev runs both in one process. Each command's schema comes from its type hints, so the SDK refuses bad arguments before your code runs.

The SDK agent connects only to a gateway on the same computer. A remote Linux gadget transport is planned. See the project roadmap.

Add your hardware

Put your GPIO, I2C or serial code inside the command function. Plain functions run in a worker thread, so blocking calls are fine; async def works too. Return what the device now reports. Set simulated=False only when your code really controls hardware.

from typing import Annotated

from grok_gadgets_linux import Range


@lamp.command("Set the brightness from 0 to 100", name="level.set")
def level(level: Annotated[int, Range(0, 100)]) -> dict:
    # pwm.duty(level)  <- your hardware call goes here
    return {"level": level}

Events, shutdown hooks, the original Device API and limits are in the developer guide.

Run it as a service

Next to a long-running grok-gadgets-gateway serve, give the gadget its own token:

grok-gadgets-gateway enroll desk-lamp --token-file desk-lamp.token
grok-linux-agent --factory-file ./my_gadget.py --token-file desk-lamp.token

The agent re-reads the token file on every connection, so enroll --rotate needs no restart. A systemd user unit template, reconnect limits and exit codes are in the operation guide (systemd is not yet verified).

Platforms

Python 3.11–3.14. CI runs on Ubuntu every night, including the README quick start and the gateway integration tests against gateway main. Raspberry Pi 3, 4, 5 and Zero 2 W have PyPI wheels for every dependency. The armv6l models (Pi Zero, Zero W, Pi 1) need a Rust toolchain for rpds-py. An outside Raspberry Pi 5 report awaits review and a released-version rerun. It is not accepted hardware evidence; see the project status.

Troubleshooting

The agent prints Agent stopped (<code>). <hint> and exits with a distinct code.

Never retry an uncertain physical action with a new command ID: read the state first. Gadget files run trusted local code; never run code from a conversation.

Community

Show your gadget, ask questions and share ideas on r/GrokGadgets. Report bugs in GitHub Issues. New here? Pick a good first issue and read CONTRIBUTING. Help: SUPPORT. Security: SECURITY. Keep tokens and household details out of public posts. 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. Detailed verification records: launch verification and historical record.

Project discussion

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