Created by @TroveXsc. Follow on X for project updates!
Skip Grok Bot sign-in in external-provider mode. Use your own models. Run your own cloud desktop. Keep your work across restarts.
Connect the original Grok Bot interface to a model service you choose, run its desktop locally with Docker or on your own Linux server, and persist Bots, conversations, skills, routines, workspace files and browser profiles. Enable the integration or restore the official app with one click.
English · 简体中文 · 繁體中文 · 日本語 · ไทย · 한국어 · Español · Français · Deutsch · Português · Русский · العربية
For learning and experimentation only. Thanks to Elon Musk for providing such great software. We encourage everyone to use and support the official version. If you would like to explore Grok Bot’s interactions, you are welcome to try this project.
An independent community project, with no official affiliation or endorsement.
- Explore Grok Bot without signing in: external-provider mode uses a separate local identity and workspace. Official account services remain separate.
- Choose your models: use Responses, Chat Completions or Anthropic Messages, refresh a provider’s model list, enter a model ID, and adjust reasoning effort and token limits.
- Bring your own desktop: use Docker on your Mac or save an SSH connection to a self-hosted Linux server. View and control the desktop from Grok Bot.
- Keep your work: Bot data, conversations, skills, routine journals, workspace files and browser profiles live in persistent storage. Container recreation and app restoration preserve that storage.
- Run routines and share templates: schedule tasks, inspect skills, and import or export Bot templates. Imported routines start paused.
- Return to the official app: restore the original application before using its official updater, then check compatibility and enable again.
Download v0.3.2 from Releases. Choose arm64 for Apple Silicon or x64 for Intel. Current macOS builds are unsigned and not notarized by Apple.
- Install the official Grok Bot application. Start Docker Desktop or a compatible Docker engine for a local desktop.
- Open Grok Bot Companion → Model service. The provider address starts blank. Enter your own address, API key, protocol, model and reasoning effort, then test the connection.
- Open Client → Enable External Provider. The first run downloads the required runtimes; progress stays at the top.
- Open Grok Bot. Model and desktop controls are also available under Settings → External Provider.
- Select Cloud desktop to start a local desktop or add your own server.
Companion adapts your installed official application reversibly. The download contains the companion and its adapters; official runtimes are obtained separately from their public sources.
English is the default for the app and documentation. Choose English, Simplified Chinese, Traditional Chinese, Japanese, Thai, Korean, Spanish, French, German, Portuguese, Russian or Arabic in the language selector. Follow system is an optional selection. Explicit language choices are saved, and Arabic supports right-to-left layout.
Bot names, skills, messages, model IDs and your form inputs retain their original content.
There is no bundled model-service address, shared API key or preconfigured private server. Saved connection addresses are hidden in settings until you choose Show. Connection summaries and diagnostic messages avoid exposing addresses, credentials and local identity details.
Local model keys are stored in the macOS Keychain. Self-hosted server keys are stored separately on that server with restricted file permissions. Keep your own data and backups private; template exports omit connection credentials and messages, but skill text may contain information you wrote yourself.
A Bot’s explicitly selected model takes priority over the default model. Changes apply on the next turn. Reasoning options depend on your provider; Anthropic Messages currently uses the provider’s reasoning defaults.
Open Cloud desktop → Add server, enter your own SSH connection details, verify the host fingerprint, and choose Test connection → Deploy / update server → Use this connection. Configure the server’s model service after switching. See the server guide.
The server runs the model proxy, Bot engine, scheduler and Linux desktop. Server tasks can continue after the Mac disconnects. Tasks that require Mac tools or a human approval still depend on those resources being available.
Each local or server connection has its own workspace. Switching connections does not merge or migrate data. Removing a connection does not delete server data. Persisted data survives application and container restarts, but deleting the data directory or losing its disk still requires a backup to recover. Files outside the persisted workspace and temporary container software are not automatically retained.
Choose native approval rules, ask every time, or auto-approve. Native team limits and macOS screen-recording/accessibility permissions still apply.
Routines retain their schedules, time zones and execution journals. Keep the host and Docker running. Missed cycles coalesce into one recovery run; interrupted actions are not blindly replayed. Closing a window does not stop a running Docker scheduler. After restarting a local Mac, open Companion or the enabled Grok Bot to start the local model proxy.
Use Templates & skills to inspect skills and import or export Bot templates. Imported routines remain paused until enabled. Official sharing links and marketplace services still depend on the official account services.
To update Grok Bot, choose Restore and open official update, use the official updater, then check compatibility and enable again. To update Companion, replace it with the new package, open it, and enable again to refresh the adapter. Existing workspaces remain in place.
The adapter checks JavaScript structure instead of assuming every version is compatible. Known structural checks cover Grok Bot 0.43.0 and 0.47.0; future versions may require adaptation. Voice, official cloud sync and official marketplace/account services are outside this integration’s compatibility scope. See architecture and testing.
Use macOS, Node.js 24+ and npm. Local desktop development also needs Docker.
npm ci
npm test
npm run check
npm run dev
npm run dist:macUI translations live in ui/locales/; packaging rebuilds the catalog. GROK_LOCAL_STATE_DIR can select an isolated development data directory. Do not run competing engines against the same workspace. The CI example can be installed as a GitHub workflow. Configure your own signing and notarization before distributing signed macOS builds.