@adam91holt/grokbot-sdk

TypeScript SDK for a running Grok Bot host. It gives you a typed client over the host's local HTTP gateway, plus readers for the host's on-disk sand-data directory.

This package does not invent endpoints. Command names and response shapes come from the host.

Requires Node 22+.

npm i @adam91holt/grokbot-sdk

From this repo: cd sdk && npm ci && npm test && npm run build. The CLI is npx grokbot.

flowchart LR
  You[Your app, CLI, or Grok Bot agent] --> SDK["@adam91holt/grokbot-sdk"]
  SDK -->|"HTTP POST /api/<command>"| GW[Host gateway]
  SDK -->|"local file reads"| Disk["sand-data/"]
  GW --> Host[Grok Bot host process]
  Host --> Disk

Prefer the gateway whenever the host is running. It is the authoritative live view, and the host owns its own writes — watchers, dreaming metadata, and cross-shard memory merge all happen there. Disk writes bypass all of that.

Reach for GrokBotDisk when:

• the host process is not running, or you have no token
• you want to grep or bulk-scan raw files rather than page through an API
• you want something only disk exposes: transcript JSONL, an agent's store.db, or search-index.db

sand-data defaults to /home/box/sand-data (alias /home/box/agent-data). Override with SAND_DATA_ROOT.

import { GrokBot, GrokBotDisk } from "@adam91holt/grokbot-sdk";

const bot = new GrokBot();
const health = await bot.health();
const agents = await bot.listAgents();

console.log(health.ok, agents.length);

// Same machine, no token needed, no host process needed:
const disk = new GrokBotDisk();
console.log(disk.listAgents().length);

health() is unauthenticated. Everything else that hits POST /api/<command> uses the gateway token (from gateway.json or SAND_GATEWAY_TOKEN). Never log or commit the token.

A Grok Bot agent on the same computer as the host can clone this repo and drive the local gateway:

git clone https://github.com/adam91holt/grokbot-sdk.git
cd grokbot-sdk/sdk
npm ci

Then new GrokBot() is enough — no configuration. The SDK reads sand-data/gateway.json on this computer for the port and token, and rewrites wildcard binds (0.0.0.0 / ::) to 127.0.0.1.

See docs/grok-bot.md.

The gateway is not on the public internet. From another computer you need a reachable host URL and the token in the environment.

A tailnet (for example Tailscale) is the usual way: give the Grok Bot computer a stable name, then:

export GROKBOT_GATEWAY_URL=http://your-host:1340
export SAND_GATEWAY_TOKEN=...   # from the host's gateway.json — do not git this

const bot = new GrokBot({ gatewayUrl: "http://your-host:1340" });

SAND_GATEWAY_URL is an alias. Any reachable path works (VPN, SSH tunnel, LAN). The token still comes from SAND_GATEWAY_TOKEN or a local gateway.json.

Note that GrokBotDisk does not work across machines — there is no remote disk mode.

See docs/remote.md.

These are SDK loops over real host commands. There is no waitForCompletion host API.

const receipt = await bot.sendAsAgent({
  to: "Ada",
  message: "status only",
});

to: "all" is refused. Default bus seats are throwaways and get deleted.

createAgent / runOnce always POST a string name and description (minted / "" when omitted) so the host does not crash on name.trim() / description.trim().

Same discovery as new GrokBot(). GROKBOT_GATEWAY_URL wins when set.

npx grokbot health
npx grokbot agents
npx grokbot send Ada "status only"
npx grokbot run-once "Reply with PONG 1"
npx grokbot send-as --to Ada "status only"
npx grokbot job submit ./job.json

agents falls back to disk if the gateway call fails. transcript, automations, and workflows read disk directly.

health and discovery never print the token (hasToken is a boolean). See docs/cli.md and sdk/README.md.

• Never commit gateway.json, .env, or tokens.
• Transcripts and store.db are sensitive. The CLI prints metadata unless you pass --raw.
• Destructive host commands are not first-class methods. They need allowUnsafeCommands or commandUnsafe().
• store.db and search-index.db are opened read-only. The SDK never writes them.

• Use from Grok Bot
• Remote / tailnet
• CLI
• API reference
• Releasing / npm publish

This repository is the SDK only (sdk/). It does not ship the Grok Bot host, desktop, or an ops dashboard.

Live sand-data is not in git: tokens, secrets, chats, transcripts, store.db.

MIT