Via the console
- On the Secrets page, create a secret with the xAI provider and paste your API key — you only do this once, and the key never enters the sandbox.
- Go to console.superserve.ai and click Create sandbox.
-
Pick the
superserve/node-22template. -
Under Advanced Options → Secrets, bind that secret to
XAI_API_KEY. -
Create the sandbox, open its Terminal, and run:
Via the SDK
XAI_API_KEY as usual, but its value is a stand-in token — the real key is attached only on requests to the xAI API, never exposed to the agent.
Open the sandbox in the console, launch the terminal, and run grok. With XAI_API_KEY set, Grok Build signs in with the key and skips the browser login.
Run headless
Pass a prompt with-p. Grok Build runs it in the sandbox, prints its final answer, and exits. Add --always-approve so the agent runs shell commands and edits files without stopping to ask for approval.
An agent run can take several minutes. Pass output callbacks to each run() that starts the agent: a streamed run() gets keepalive messages while the agent works, so the connection stays open. A run() without callbacks gets no response until the command ends, and in TypeScript on Node.js it fails after 300 seconds, even with a longer timeoutMs. See Streaming output.
grok -p keeps waiting after the agent’s turn ends. For a task that can start a server, tell the agent in the prompt to stop the server before it finishes, for example "... Test it, then stop the server before you finish."
Grok Build picks a default model unless you pass -m, for example grok -m grok-4.3 -p "...". The JSON output below names the model that ran in modelUsage.
Auto-approved commands stay inside the sandbox and can’t touch your machine, but the sandbox can still reach the internet. Use network rules to limit where it can connect. With an API key, Grok Build needs only
api.x.ai to run, plus registry.npmjs.org if you install it after you restrict the network. If you deny all other traffic, also allow the sandbox’s DNS resolvers, 1.1.1.1/32 and 8.8.8.8/32, so these names resolve.Get JSON output
Use--output-format json to get one JSON object when the run ends. It holds the final answer in text, the session ID in sessionId, and the token usage and cost. If the run fails, for example because the key is not valid, Grok Build exits with a non-zero code and prints an object with type: "error" and a message.
These runs pass only a stderr callback, so the JSON on stdout isn’t printed while it arrives. The callback still keeps the connection open, and result.stdout holds the complete JSON when the run ends.
--output-format streaming-json instead to get one JSON event per line while the agent works.
Get structured output
Pass a JSON Schema to--json-schema together with --output-format json. The answer that matches the schema is in structuredOutput.
Continue a session
Grok Build saves each run as a session in~/.grok/sessions. Pass the session ID to --resume to send a follow-up with the earlier context, or use -c to continue the most recent session in the current directory.
Work on a repository
Clone a repository into the sandbox, stream Grok Build’s output while it works, then read the diff.Persist sessions
Delete when finished
A paused sandbox is kept until you delete it. When you no longer need the sandbox, delete it. This also deletes its files and saved state.Sandbox.killById() (TypeScript) or Sandbox.kill_by_id() (Python). To delete paused sandboxes automatically, see Auto-delete.