grok-bot-setup

August 17, 2026 · View on GitHub

CLI to point Grok Bot at custom model providers — DeepSeek, Claude, Grok, OpenAI, OpenRouter, ChatGPT/Codex, or any OpenAI-compatible URL.

npm install -g grok-bot-setup
adapters

After this VM / Sand box resets (one line):

curl -fsSL https://raw.githubusercontent.com/BlockedPath/grok-bot-setup/main/scripts/bootstrap.sh | bash

That clones/updates the repo, patches ~/sand-host, installs CLIProxy v7 + Management Center, seeds xai-inference.env, and restarts the host. Then claude login and, if you use them, export MODEL_API_KEY=… DEEPSEEK_API_KEY=… and run adapters recover again so keys land in CLIProxy.

Install

npm (recommended)

# one-shot
npx grok-bot-setup

# global (puts `adapters` on PATH)
npm install -g grok-bot-setup
adapters help

Also available as the grok-bot-setup command (same CLI).

Other ways

curl (single script)

# full setup (hook + CLIProxy + PATH launcher) — use this after a wipe
curl -fsSL https://raw.githubusercontent.com/BlockedPath/grok-bot-setup/main/scripts/bootstrap.sh | bash

git clone

git clone https://github.com/BlockedPath/grok-bot-setup.git
cd grok-bot-setup
./adapters

Quick start

# 1) Install optional proxies + login CLIs (as needed)
adapters install all
adapters install login-agents

# 1b) Optional extra tools
adapters install herdr    # agent runtime — keeps coding-agent terminals alive (herdr.dev)
adapters install ghostty  # terminal emulator (ghostty.org)
adapters install tailscale  # mesh VPN — reach this box from anywhere (tailscale.com)
adapters install zellij    # terminal multiplexer — sessions inside herdr (zellij.dev)
adapters install lazygit   # TUI git client — fast repo work (github.com/jesseduffield/lazygit)

# 2) Log in to the providers you care about
claude login    # Claude Pro/Max OAuth
grok login      # Grok session
codex login     # ChatGPT / Codex OAuth

# 3) Point Grok Bot at a provider
adapters use deepseek
# or: claude | grok-session | openai | openrouter | xai-api | litellm | openai-oauth | direct | cursor

# 4) Check status anytime
adapters status

Or just run adapters with no args for the interactive menu.

Prerequisites

Sand / Grok Bot host (~/sand-host, ~/sand-data)
bash, curl, python3
Only if you use that adapter:
- CLIProxy (Claude OAuth) → Go
- LiteLLM bridge → uv
- openai-oauth (Codex) → Node / npx

Commands

Command	What it does
`adapters`	Interactive menu
`adapters status`	Current provider + adapter ports
`adapters check-logins`	Claude / Grok / Codex CLI login state
`adapters sync-claude [--refresh]`	Bidirectional Claude OAuth token sync (CLIProxy ↔ `claude login`)
`adapters effort high\|medium\|low\|xhigh\|off`	Set reasoning effort (restarts host)
`adapters install [target]`	Download adapters or login CLIs
`adapters start [target]`	Start local proxies
`adapters stop [target]`	Stop local proxies
`adapters use <profile>`	Switch Grok Bot provider (also installs the host hook)
`adapters models`	List models from CLIProxy (`:8317`) or the current gateway
`adapters model <id>`	Switch Sand to that model (keeps the current CLIProxy/base)
`adapters patch-host`	Copy `xai-prompt-session.cjs` into `~/sand-host` and inject the createSession hook
`adapters recover`	After a Sand reset: reinstall hook + CLIProxy v7 + restart host
`adapters management`	Print CLIProxy Management Center URL + key
`adapters restart-host`	Restart Sand host to pick up config
`adapters help`	Full help

Install targets

all · cliproxy · litellm · openai-oauth · claude · grok · codex · herdr · ghostty · tailscale · zellij · lazygit · login-agents

Extra tools

Target	Tool	Why
`herdr`	herdr.dev	Agent runtime — holds real terminals open so coding-agent work survives a closed lid; reattach from anywhere
`ghostty`	ghostty.org	Fast GPU terminal emulator (`.deb` from `mkasberg/ghostty-ubuntu`)
`tailscale`	tailscale.com	Mesh VPN — reach this box securely from any device; pairs with herdr for always-attachable terminals
`zellij`	zellij.dev	Terminal multiplexer — run sessions inside herdr and reattach from anywhere (override version: `ZELLIJ_VERSION=v0.44.3`)
`lazygit`	github.com/jesseduffield/lazygit	TUI git client — fast staging/committing on a headless box (apt / brew)

adapters install tailscale runs the official installer, then authenticate with sudo tailscale up.

adapters install ghostty picks the right .deb for your distro (Debian trixie/bookworm, Ubuntu 24.04/25.10/26.04; amd64/arm64). Override the version with GHOSTTY_VERSION=1.3.1 adapters install ghostty.

Start / stop targets

all · cliproxy (:8317) · litellm (:4000) · openai-oauth (:10531)

The cliproxy start now also launches a watchdog that keeps the proxy up and re-syncs Claude OAuth tokens every 60s (either side may rotate them and revoke the other's).

CLIProxy v7+ serves the Management Center at http://127.0.0.1:8317/management.html. The management key is written to ~/.local/share/grok-bot-adapters/cliproxy-api/management.key (not the same as the proxy API key sand-cliproxy).

Provider profiles (`adapters use …`)

Profile	Backend	Auth
`deepseek`	api.deepseek.com	DeepSeek API key
`claude` / `cliproxy`	CLIProxy `:8317` or LiteLLM	`claude login` or Console API key
`grok-session` / `grok`	Grok cli-chat-proxy	`grok login`
`xai-api` / `xai`	api.x.ai	xAI API key
`openai`	OpenAI Platform	`OPENAI_API_KEY`
`openrouter`	OpenRouter	`OPENROUTER_API_KEY`
`litellm` / `bridge`	LiteLLM `:4000`	master key in bridge `.env`
`openai-oauth` / `codex`	openai-oauth `:10531`	`codex login`
`direct`	Any OpenAI-compatible URL	`--base-url` + `--key` + `--model`
`cursor` / `stock`	Stock Cursor path	disables custom provider

Flags

adapters use deepseek --model deepseek-chat --key sk-...
adapters use claude --model claude-opus-5 --oauth --thinking enabled --reasoning-effort medium
adapters use grok-session --model grok-4.6 --effort high
adapters use grok-session --model grok-4.6 --effort medium   # safer multi-agent / groups
adapters effort medium                                       # change effort only
adapters use openai --model gpt-4o --key sk-...
adapters use direct --base-url https://example.com/v1 --model my-model --key KEY

--model ID — skip model prompt
--key KEY — skip API-key prompt (or use env vars like OPENAI_API_KEY)
--auth oauth|api_key — Claude auth mode
--thinking enabled|disabled — model thinking / chain-of-thought (writes SAND_XAI_THINKING)
--effort / --reasoning-effort low|medium|high|xhigh — writes SAND_XAI_REASONING_EFFORT
--thinking medium — shorthand for enabled + effort medium (also low / high)
--no-restart — write config without restarting the host

Host hook (required)

Stock Grok Bot ignores xai-inference.env until the host is patched. This repo ships:

File	Role
`xai-prompt-session.cjs`	OpenAI-compatible inference session (CLIProxy / LiteLLM / xAI / …)
`scripts/ensure-xai-inference.sh`	Copies that module next to `host-main.cjs` and injects the createSession hook

adapters use … and adapters restart-host run the installer. After a host bundle upgrade:

adapters patch-host
adapters restart-host

After a Sand reset

A box wipe deletes ~/sand-host patches, ~/sand-data/xai-inference.env, and local CLIProxy. GitHub is the source of truth.

curl -fsSL https://raw.githubusercontent.com/BlockedPath/grok-bot-setup/main/scripts/bootstrap.sh | bash
# same as: git clone … && ./adapters recover

adapters recover / scripts/bootstrap.sh:

Clone or fast-forward ~/grok-bot-setup to origin/main
Put adapters on PATH
Copy xai-prompt-session.cjs and inject the host hook
Seed ~/sand-data/xai-inference.env from the example if missing
Install CLIProxy v7+ + Management Center
Ensure Meta + DeepSeek model aliases exist (keys from MODEL_API_KEY / DEEPSEEK_API_KEY if you exported them)
Restart the host

Then:

claude login
grok login            # optional
export MODEL_API_KEY='…'          # Meta
export DEEPSEEK_API_KEY='…'       # DeepSeek
adapters recover                   # writes keys into CLIProxy
adapters models
adapters model claude-opus-5       # or muse-spark-1.2-contributor / deepseek-v4-flash / …

OAuth logins and paid API keys are not in git. Model lists are (examples/cliproxy-openai-compat.yaml).

Multi-agent safety (host module)

Shipped as xai-prompt-session.cjs and installed to ~/sand-host/xai-prompt-session.cjs:

Env	Default	Meaning
`SAND_XAI_MAX_TOKENS`	`8192`	Cap completion length (`0` = omit)
`SAND_XAI_MAX_INPUT_CHARS`	`280000` on Gemini / `400000` else	Drop old turns so input stays under the provider cap
`SAND_XAI_MAX_TOOL_CHARS`	`12000`	Truncate a single tool result (file dumps)
`SAND_XAI_PROMOTE_REASONING`	off	Do not re-inject reasoning as normal chat content (stops monologue loops)

For group chats prefer: adapters effort medium

What it writes

Path	Purpose
`~/sand-data/xai-inference.env`	Active provider config (loaded by the host)
`~/sand-data/settings.json`	`agentDefaultModel` (when switched)
`~/.local/share/grok-bot-adapters/`	Local proxy trees from `adapters install`

Override the local data dir with ADAPTERS_DATA=/path.

Docs

Full runbook: docs/GUIDE_CUSTOM_INFERENCE.md
HTML: docs/GUIDE_CUSTOM_INFERENCE.html
CLI: adapters help
Repo: https://github.com/BlockedPath/grok-bot-setup
npm: https://www.npmjs.com/package/grok-bot-setup

Contributing

Contributing guide
Code of conduct
Bug / feature forms open automatically when you file an issue
PRs use .github/PULL_REQUEST_TEMPLATE.md