diff --git a/.github/workflows/publish-cli.yml b/.github/workflows/publish-cli.yml index c1cc269..830062d 100644 --- a/.github/workflows/publish-cli.yml +++ b/.github/workflows/publish-cli.yml @@ -37,6 +37,7 @@ on: - 'dsh/**' - 'hermes/**' - 'openclaw/**' + - 'grok/**' - '.claude-plugin/**' - '.github/workflows/publish-cli.yml' push: @@ -145,6 +146,13 @@ jobs: if [ ! -d hermes ]; then echo "no hermes/ folder on this ref; skipped"; exit 0; fi export HOME="$(mktemp -d)" hermes plugins validate ./hermes + - name: Grok Build plugin + run: | + set -euo pipefail + if [ ! -d grok ]; then echo "no grok/ folder on this ref; skipped"; exit 0; fi + export HOME="$(mktemp -d)" + curl -fsSL https://x.ai/cli/install.sh | bash -s "$(node -p "require('./cli/e2e/clients.json').grok.version")" + "$HOME/.grok/bin/grok" plugin validate ./grok - name: OpenClaw plugin run: | set -euo pipefail diff --git a/README.md b/README.md index ceba78c..93796cb 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,7 @@ Most agents need no plugin: add the MCP server `https://mcp.box.simular.ai/mcp` | Any of Claude Code, Codex, Cursor, OpenCode, Gemini CLI, Hermes, OpenClaw, VS Code (and steps for Claude Desktop) | [`cli/`](cli/) | OAuth; personal key with `--auth key` for Hermes and OpenClaw | `npx @simular-ai/box connect` (check with `npx @simular-ai/box doctor`) | | Hermes Agent | [`hermes/`](hermes/) | Personal key (`cb_...`) in `MCP_BOX_API_KEY`; OAuth optional | [hermes/README.md](hermes/README.md) | | ChatGPT and Codex (OpenAI plugin directory) | [`openai/`](openai/) | OAuth, once in the browser | Listed by OpenAI after review; build the upload with `openai/build-zip.sh` ([openai/README.md](openai/README.md)) | +| Grok Build | [`grok/`](grok/) | OAuth, once in the browser (`/mcps`, then `i`) | `/marketplace`, find **box**, press `i` ([grok/README.md](grok/README.md)) | ## Offload: move a coding task into your box and back @@ -28,5 +29,6 @@ Add a folder named after the agent with its own manifest, MCP config and, where - `dsh/`: bump `version` in `dsh/package.json`, then push a tag `dsh-vX.Y.Z`. The release workflow attaches `dsh-box.tgz`. - `openai/`: bump `version` in `openai/plugin.json` and `publication.release_notes`, run `openai/build-zip.sh`, upload the ZIP at platform.openai.com/plugins. - `hermes/`: bump `version` in `hermes/plugin.json`. Users copy the folder by hand until box is in the Hermes plugin catalog. +- `grok/`: bump `version` in `grok/.grok-plugin/plugin.json`, then open a PR to [xai-org/plugin-marketplace](https://github.com/xai-org/plugin-marketplace) that moves the `box` entry's `sha` to the new commit and regenerates its index. - The Claude plugin's CLI pin: since 1.0.0, `@simular-ai/box` on npm is the Rust CLI released from [simular-ai/box-cli](https://github.com/simular-ai/box-cli). To move the plugin to a new CLI release, change the exact pin `npx -y @simular-ai/box@X.Y.Z` in `claude/skills/box-offload/SKILL.md` and bump `version` in `claude/.claude-plugin/plugin.json` in one PR (CI fails unless every pin under `claude/` names the same exact version and that version is on npm; never a range, because the Claude directory review requires that what runs is what it read). - `cli/`: the JavaScript CLI (0.2.x). It no longer publishes to npm: its trusted publisher on `@simular-ai/box` was removed when the Rust 1.0.0 shipped, so do not push `cli-v*` tags. The endpoint and CLI changes now go to simular-ai/box-cli. diff --git a/cli/e2e/clients.json b/cli/e2e/clients.json index 7e1bb8f..3d4a51a 100644 --- a/cli/e2e/clients.json +++ b/cli/e2e/clients.json @@ -6,5 +6,6 @@ "gemini-cli": { "npm": "@google/gemini-cli@0.66.0" }, "openclaw": { "npm": "openclaw@2026.11.1" }, "hermes": { "git": "https://github.com/NousResearch/hermes-agent", "tag": "v0.22.6" }, + "grok": { "version": "1.0.70" }, "cursor": { "cursorAgent": "2026.10.22-27dcf5f" } } diff --git a/grok/.grok-plugin/plugin.json b/grok/.grok-plugin/plugin.json new file mode 100644 index 0000000..1b25cb2 --- /dev/null +++ b/grok/.grok-plugin/plugin.json @@ -0,0 +1,13 @@ +{ + "name": "box", + "version": "0.1.0", + "description": "Give Grok a computer of its own: a cloud Linux desktop with Chrome and a shell that it drives over MCP, while your own computer stays free. You sign in once in the browser; no key to paste.", + "author": { + "name": "Simular", + "url": "https://simular.ai" + }, + "homepage": "https://box.simular.ai", + "repository": "https://github.com/simular-ai/box-plugin", + "license": "MIT", + "keywords": ["box", "simular box", "box by simular", "computer-use", "cloud-computer"] +} diff --git a/grok/.mcp.json b/grok/.mcp.json new file mode 100644 index 0000000..25bd95c --- /dev/null +++ b/grok/.mcp.json @@ -0,0 +1,8 @@ +{ + "mcpServers": { + "box": { + "type": "http", + "url": "https://mcp.box.simular.ai/mcp" + } + } +} diff --git a/grok/LICENSE b/grok/LICENSE new file mode 100644 index 0000000..3514bf9 --- /dev/null +++ b/grok/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Simular LLC + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/grok/README.md b/grok/README.md new file mode 100644 index 0000000..b4c1d9d --- /dev/null +++ b/grok/README.md @@ -0,0 +1,32 @@ +# box for Grok Build + +[box](https://box.simular.ai) gives Grok a computer of its own: a cloud Linux desktop with Chrome and a shell that it drives over MCP, while your own computer stays free. Grok can browse sites (including ones behind a login), fill forms, use desktop apps and run commands there. You can watch the box live and take over at https://box.simular.ai/box. + +The plugin adds the box MCP server (`https://mcp.box.simular.ai/mcp`) and a `box` skill that tells Grok which tool to use for what. + +## Install + +1. Install Grok Build and sign in (see the [Grok Build docs](https://docs.x.ai/build/overview)), then run `grok`. +2. Open the marketplace with `/marketplace`, find **box** and press `i` to install it. + Until box is listed in xAI's marketplace, install it straight from this repo instead: `grok plugin install simular-ai/box-plugin#grok`. +3. Open the MCP servers tab with `/mcps`, select **box** and press `i` to sign in. Your browser opens the box sign-in page; sign in once with your box account (new accounts get free credit). +4. Once **box** shows ready, ask Grok for anything that needs a computer, for example "open Hacker News in my box and summarize the top five posts". + +## Sign-in + +The plugin uses OAuth only: you sign in in the browser once and Grok keeps the token. It carries no key, so there is nothing to paste or store in the package. + +## What it touches + +- Network: only `https://mcp.box.simular.ai/mcp` (box's MCP server) and the box sign-in page. +- Local files: none. The skill only tells Grok how to use box's tools; commands and file edits run on the box, not on your machine. + +## Links + +- Docs: https://box.simular.ai/docs/mcp +- Privacy policy: https://www.simular.ai/product-sai/privacy +- Terms of use: https://www.simular.ai/terms-of-use + +## License + +MIT. See [LICENSE](LICENSE). diff --git a/grok/skills/box/SKILL.md b/grok/skills/box/SKILL.md new file mode 100644 index 0000000..aa9255e --- /dev/null +++ b/grok/skills/box/SKILL.md @@ -0,0 +1,22 @@ +--- +name: box +description: Use box, a cloud Linux computer with Chrome and a shell, when a task needs a real computer - browsing sites (including ones behind a login), filling forms, using desktop apps, or running commands somewhere other than the user's machine. +--- + +# Use box + +box is the user's own cloud Linux desktop. Its tools come from the `box` MCP server. The first call signs the user in through their browser once; after that it just works. A sleeping box wakes on the first call, which can take a few seconds. + +## Pick the right tool + +- **Shell and files:** `shell` runs a command; `read_file`, `write_file`, `edit_file` and `list_dir` work on the box's files. Prefer these whenever the task can be done without the screen. +- **Web pages:** `browser_navigate` opens a URL, `browser_snapshot` or `browser_read` reads the page, `browser_click`, `browser_type` and `browser_fill` act on elements from the last snapshot, `browser_tabs` manages tabs, `browser_fetch` fetches a URL without rendering. Re-snapshot after the page changes; element refs go stale. +- **Desktop apps:** send a whole GUI plan in one `gui_plan` call (open the app, menu, click, type, wait, save) instead of a chain of single clicks. Use `desk` for one accessibility-tree action, `computer_act` and `computer_state` for raw pointer and keyboard work, and `script_run` for loops over many items. +- **Seeing the screen:** `screenshot` when you need to look; don't take one after every step. +- **The box itself:** `box_status`, `box_list`, `box_wake`, `box_hibernate`, `box_save` and `box_upgrade`. + +## Working with the user + +- The user can watch the box live and take over at https://box.simular.ai/box. Mention it for long tasks. +- When a step needs the user (a sign-in, a password, a 2FA code, a captcha, a payment), stop and ask them to do it on that page, then continue. Never ask for passwords in chat. +- Report what you did and anything you saved on the box, with paths.