Grok

Image updates

Ready-made agent images are updated every morning with the current CLI version. To keep a fixed image version, pin a template version.

Grok Build is an xAI agent for working with files, commands, and external tools. The ready-made grok template contains the official CLI. Your application starts it through the AgentBox commands API and retrieves a response or output file.

Connect

Install the AgentBox SDK and set AGENTBOX_API_KEY.

The xAI key is read from XAI_API_KEY and passed only to the agent process. The examples select grok-4.3. Run grok models inside the sandbox with your key to list available models.

For model access, you can use the AgentBox HTTPS proxy https://sandbox-proxy.agentbox.ru:65181.

The examples pass HTTPS_PROXY, HTTP_PROXY, and NO_PROXY to the agent process. These settings may also affect other requests made by the agent and its child processes. Connections to localhost and 127.0.0.1 remain direct.

Prepare a delivery summary

The example uploads a delivery export and asks Grok to write delayed orders and their known causes to exceptions.md. The application then reads the file through the SDK.

mjs

import { Sandbox } from "@abox-dev/sdk";

const apiKey = process.env.XAI_API_KEY;
if (!apiKey) throw new Error("XAI_API_KEY is required");
const proxy =
  process.env.SANDBOX_PROXY_URL ?? "https://sandbox-proxy.agentbox.ru:65181";
const sandbox = await Sandbox.create("grok", { timeoutMs: 600_000 });
try {
  await sandbox.files.makeDir("/home/user/work");
  await sandbox.files.write(
    "/home/user/work/shipments.csv",
    `order,customer,status,note
1042,Acme,delayed,Awaiting warehouse pickup
1043,Northwind,delivered,Delivered on September 18
1044,Contoso,delayed,Address confirmation required
`,
  );
  await sandbox.files.write(
    "/home/user/work/task.txt",
    "Read shipments.csv and write exceptions.md for the logistics team: delayed orders and their known reasons.",
  );
  const result = await sandbox.commands.run(
    "grok --always-approve --sandbox off --model grok-4.3 --prompt-file task.txt",
    {
      cwd: "/home/user/work",
      timeoutMs: 300_000,
      envs: {
        XAI_API_KEY: apiKey,
        HTTPS_PROXY: proxy,
        HTTP_PROXY: proxy,
        NO_PROXY: "localhost,127.0.0.1",
      },
      onStderr: (chunk) => process.stderr.write(chunk),
    },
  );
  console.log(result.stdout);
  console.log(
    "exceptions.md\n" +
      (await sandbox.files.read("/home/user/work/exceptions.md")),
  );
} finally {
  await sandbox.kill();
}

import os
import sys
from agentbox import Sandbox

api_key = os.environ["XAI_API_KEY"]
proxy = os.getenv("SANDBOX_PROXY_URL", "https://sandbox-proxy.agentbox.ru:65181")
sandbox = Sandbox.create("grok", timeout=600)
try:
    sandbox.files.make_dir("/home/user/work")
    sandbox.files.write(
        "/home/user/work/shipments.csv",
        """order,customer,status,note
1042,Acme,delayed,Awaiting warehouse pickup
1043,Northwind,delivered,Delivered on September 18
1044,Contoso,delayed,Address confirmation required
""",
    )
    sandbox.files.write(
        "/home/user/work/task.txt",
        "Read shipments.csv and write exceptions.md for the logistics team: delayed orders and their known reasons.",
    )
    result = sandbox.commands.run(
        "grok --always-approve --sandbox off --model grok-4.3 --prompt-file task.txt",
        cwd="/home/user/work",
        timeout=300,
        envs={
            "XAI_API_KEY": api_key,
            "HTTPS_PROXY": proxy,
            "HTTP_PROXY": proxy,
            "NO_PROXY": "localhost,127.0.0.1",
        },
        on_stderr=lambda chunk: print(chunk, end="", file=sys.stderr),
    )
    print(result.stdout)
    print("exceptions.md\n" + sandbox.files.read("/home/user/work/exceptions.md"))
finally:
    sandbox.kill()

package main

import (
	"context"
	"errors"
	"fmt"
	"log"
	"os"
	"time"

	"github.com/abox-dev/sdk/packages/go-sdk"
)

func run() (err error) {
	apiKey := os.Getenv("XAI_API_KEY")
	if apiKey == "" {
		return errors.New("XAI_API_KEY is required")
	}
	proxy := os.Getenv("SANDBOX_PROXY_URL")
	if proxy == "" {
		proxy = "https://sandbox-proxy.agentbox.ru:65181"
	}
	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
	defer cancel()
	client, err := agentbox.NewClient()
	if err != nil {
		return err
	}
	sandbox, err := client.Sandboxes.Create(ctx, &agentbox.CreateSandboxOptions{Template: "grok", Timeout: 10 * time.Minute})
	if err != nil {
		return err
	}
	defer func() {
		cleanupCtx, stop := context.WithTimeout(context.Background(), 30*time.Second)
		defer stop()
		_, cleanupErr := sandbox.Kill(cleanupCtx)
		err = errors.Join(err, cleanupErr)
	}()
	if _, err := sandbox.Files.MakeDir(ctx, "/home/user/work"); err != nil {
		return err
	}
	if _, err := sandbox.Files.WriteText(ctx, "/home/user/work/shipments.csv", `order,customer,status,note
1042,Acme,delayed,Awaiting warehouse pickup
1043,Northwind,delivered,Delivered on September 18
1044,Contoso,delayed,Address confirmation required
`, nil); err != nil {
		return err
	}
	if _, err := sandbox.Files.WriteText(ctx, "/home/user/work/task.txt", "Read shipments.csv and write exceptions.md for the logistics team: delayed orders and their known reasons.", nil); err != nil {
		return err
	}
	result, err := sandbox.Commands.Run(ctx, "sh", &agentbox.CommandOptions{
		Args: []string{"-lc", "grok --always-approve --sandbox off --model grok-4.3 --prompt-file task.txt"},
		Cwd:  "/home/user/work",
		Env: map[string]string{
			"XAI_API_KEY": apiKey,
			"HTTPS_PROXY": proxy,
			"HTTP_PROXY":  proxy,
			"NO_PROXY":    "localhost,127.0.0.1",
		},
		OnStderr: func(chunk []byte) { fmt.Fprint(os.Stderr, string(chunk)) },
	})
	if err != nil {
		return err
	}
	fmt.Println(string(result.Stdout))
	report, err := sandbox.Files.ReadText(ctx, "/home/user/work/exceptions.md", "")
	if err != nil {
		return err
	}
	fmt.Println("exceptions.md\n" + report)
	return nil
}

func main() {
	if err := run(); err != nil {
		log.Fatal(err)
	}
}

--prompt-file task.txt runs one task without the interactive UI. --always-approve permits tools without approval prompts. --sandbox off disables Grok’s additional isolation layer. The AgentBox sandbox provides the environment boundary.

The example reads the result before killing the sandbox. finally also releases it on error. The Go example uses a separate context for cleanup.

Events and session continuation

With --output-format streaming-json, Grok emits newline-delimited JSON objects. The example displays response text and tool names, waits for completion, and continues the same session with an updated delivery status.

mjs

import { Sandbox } from "@abox-dev/sdk";

const apiKey = process.env.XAI_API_KEY;
if (!apiKey) throw new Error("XAI_API_KEY is required");
const proxy =
  process.env.SANDBOX_PROXY_URL ?? "https://sandbox-proxy.agentbox.ru:65181";
const sandbox = await Sandbox.create("grok", { timeoutMs: 600_000 });
try {
  await sandbox.files.makeDir("/home/user/work");
  await sandbox.files.write(
    "/home/user/work/shipments.csv",
    `order,customer,status,note
1042,Acme,delayed,Awaiting warehouse pickup
1043,Northwind,delivered,Delivered on September 18
1044,Contoso,delayed,Address confirmation required
`,
  );
  async function execute(prompt, sessionId) {
    await sandbox.files.write("/home/user/work/task.txt", prompt);
    let pending = "",
      nextSessionId,
      terminal,
      failure;
    function event(message) {
      if (message.type === "text") process.stdout.write(message.data);
      if (message.type === "tool_call") console.log("Tool:", message.title);
      if (message.type === "end") {
        terminal = message.stopReason;
        nextSessionId = message.sessionId;
      }
      if (message.type === "error") failure = new Error(message.message);
    }
    function onStdout(chunk) {
      pending += chunk;
      let newline;
      while ((newline = pending.indexOf("\n")) !== -1) {
        const line = pending.slice(0, newline);
        pending = pending.slice(newline + 1);
        if (line.trim()) event(JSON.parse(line));
      }
    }
    await sandbox.commands.run(
      "grok --always-approve --sandbox off --model grok-4.3 --prompt-file task.txt --output-format streaming-json" +
        (sessionId ? ' --resume "$AGENT_SESSION_ID"' : ""),
      {
        cwd: "/home/user/work",
        timeoutMs: 300_000,
        envs: {
          XAI_API_KEY: apiKey,
          HTTPS_PROXY: proxy,
          HTTP_PROXY: proxy,
          NO_PROXY: "localhost,127.0.0.1",
          AGENT_SESSION_ID: sessionId ?? "",
        },
        onStdout,
        onStderr: (chunk) => process.stderr.write(chunk),
      },
    );
    if (pending.trim()) event(JSON.parse(pending));
    if (failure) throw failure;
    if (terminal !== "end_turn")
      throw new Error("Agent did not finish normally: " + terminal);
    if (!nextSessionId) throw new Error("Agent did not return a session ID");
    console.log("\nSession:", nextSessionId);
    return nextSessionId;
  }
  const sessionId = await execute(
    "Read shipments.csv and write exceptions.md for the logistics team: delayed orders and their known reasons.",
  );
  await execute(
    "The warehouse confirmed that order 1042 was picked up. Update exceptions.md and keep the other order details.",
    sessionId,
  );
  console.log(
    "exceptions.md\n" +
      (await sandbox.files.read("/home/user/work/exceptions.md")),
  );
} finally {
  await sandbox.kill();
}

import json
import os
import sys
from agentbox import Sandbox

api_key = os.environ["XAI_API_KEY"]
proxy = os.getenv("SANDBOX_PROXY_URL", "https://sandbox-proxy.agentbox.ru:65181")
sandbox = Sandbox.create("grok", timeout=600)
try:
    sandbox.files.make_dir("/home/user/work")
    sandbox.files.write(
        "/home/user/work/shipments.csv",
        """order,customer,status,note
1042,Acme,delayed,Awaiting warehouse pickup
1043,Northwind,delivered,Delivered on September 18
1044,Contoso,delayed,Address confirmation required
""",
    )

    def execute(prompt, session_id=None):
        sandbox.files.write("/home/user/work/task.txt", prompt)
        pending = ""
        next_session_id = None
        terminal = None
        failure = None

        def event(message):
            nonlocal next_session_id, terminal, failure
            if message.get("type") == "text":
                print(message["data"], end="", flush=True)
            if message.get("type") == "tool_call":
                print("Tool:", message["title"])
            if message.get("type") == "end":
                terminal = message.get("stopReason")
                next_session_id = message.get("sessionId")
            if message.get("type") == "error":
                failure = message.get("message") or str(message)

        def on_stdout(chunk):
            nonlocal pending
            pending += chunk
            while "\n" in pending:
                line, pending = pending.split("\n", 1)
                if line.strip():
                    event(json.loads(line))

        sandbox.commands.run(
            "grok --always-approve --sandbox off --model grok-4.3 --prompt-file task.txt --output-format streaming-json"
            + (' --resume "$AGENT_SESSION_ID"' if session_id else ""),
            cwd="/home/user/work",
            timeout=300,
            envs={
                "XAI_API_KEY": api_key,
                "HTTPS_PROXY": proxy,
                "HTTP_PROXY": proxy,
                "NO_PROXY": "localhost,127.0.0.1",
                "AGENT_SESSION_ID": session_id or "",
            },
            on_stdout=on_stdout,
            on_stderr=lambda chunk: print(chunk, end="", file=sys.stderr),
        )
        if pending.strip():
            event(json.loads(pending))
        if failure:
            raise RuntimeError(failure)
        if terminal != "end_turn":
            raise RuntimeError(f"Agent did not finish normally: {terminal}")
        if not next_session_id:
            raise RuntimeError("Agent did not return a session ID")
        print("\nSession:", next_session_id)
        return next_session_id

    session_id = execute(
        "Read shipments.csv and write exceptions.md for the logistics team: delayed orders and their known reasons."
    )
    execute(
        "The warehouse confirmed that order 1042 was picked up. Update exceptions.md and keep the other order details.",
        session_id,
    )
    print("exceptions.md\n" + sandbox.files.read("/home/user/work/exceptions.md"))
finally:
    sandbox.kill()

package main

import (
	"context"
	"encoding/json"
	"errors"
	"fmt"
	"log"
	"os"
	"strings"
	"time"

	"github.com/abox-dev/sdk/packages/go-sdk"
)

func run() (err error) {
	apiKey := os.Getenv("XAI_API_KEY")
	if apiKey == "" {
		return errors.New("XAI_API_KEY is required")
	}
	proxy := os.Getenv("SANDBOX_PROXY_URL")
	if proxy == "" {
		proxy = "https://sandbox-proxy.agentbox.ru:65181"
	}
	ctx, cancel := context.WithTimeout(context.Background(), 8*time.Minute)
	defer cancel()
	client, err := agentbox.NewClient()
	if err != nil {
		return err
	}
	sandbox, err := client.Sandboxes.Create(ctx, &agentbox.CreateSandboxOptions{Template: "grok", Timeout: 10 * time.Minute})
	if err != nil {
		return err
	}
	defer func() {
		cleanupCtx, stop := context.WithTimeout(context.Background(), 30*time.Second)
		defer stop()
		_, cleanupErr := sandbox.Kill(cleanupCtx)
		err = errors.Join(err, cleanupErr)
	}()
	if _, err := sandbox.Files.MakeDir(ctx, "/home/user/work"); err != nil {
		return err
	}
	if _, err := sandbox.Files.WriteText(ctx, "/home/user/work/shipments.csv", `order,customer,status,note
1042,Acme,delayed,Awaiting warehouse pickup
1043,Northwind,delivered,Delivered on September 18
1044,Contoso,delayed,Address confirmation required
`, nil); err != nil {
		return err
	}
	execute := func(prompt, sessionID string) (string, error) {
		if _, err := sandbox.Files.WriteText(ctx, "/home/user/work/task.txt", prompt, nil); err != nil {
			return "", err
		}
		var pending, nextSessionID string
		var streamErr error
		var terminal string
		event := func(line string) {
			if strings.TrimSpace(line) == "" || streamErr != nil {
				return
			}
			var message struct {
				Type       string          `json:"type"`
				Data       json.RawMessage `json:"data"`
				Title      string          `json:"title"`
				StopReason string          `json:"stopReason"`
				SessionID  string          `json:"sessionId"`
				Message    string          `json:"message"`
			}
			if err := json.Unmarshal([]byte(line), &message); err != nil {
				streamErr = err
				return
			}
			switch message.Type {
			case "text":
				var text string
				if err := json.Unmarshal(message.Data, &text); err != nil {
					streamErr = err
					return
				}
				fmt.Print(text)
			case "tool_call":
				fmt.Println("Tool:", message.Title)
			case "end":
				terminal = message.StopReason
				nextSessionID = message.SessionID
			case "error":
				streamErr = errors.New(message.Message)
			}
		}
		command := "grok --always-approve --sandbox off --model grok-4.3 --prompt-file task.txt --output-format streaming-json"
		if sessionID != "" {
			command += " --resume \"$AGENT_SESSION_ID\""
		}
		commandCtx, stop := context.WithTimeout(ctx, 5*time.Minute)
		defer stop()
		_, err := sandbox.Commands.Run(commandCtx, "sh", &agentbox.CommandOptions{
			Args: []string{"-lc", command},
			Cwd:  "/home/user/work",
			Env: map[string]string{
				"XAI_API_KEY":      apiKey,
				"HTTPS_PROXY":      proxy,
				"HTTP_PROXY":       proxy,
				"NO_PROXY":         "localhost,127.0.0.1",
				"AGENT_SESSION_ID": sessionID,
			},
			OnStdout: func(chunk []byte) {
				pending += string(chunk)
				for {
					line, rest, found := strings.Cut(pending, "\n")
					if !found {
						break
					}
					pending = rest
					event(line)
				}
			},
			OnStderr: func(chunk []byte) { fmt.Fprint(os.Stderr, string(chunk)) },
		})
		if err != nil {
			return "", err
		}
		event(pending)
		if streamErr != nil {
			return "", streamErr
		}
		if terminal != "end_turn" {
			return "", fmt.Errorf("agent did not finish normally: %s", terminal)
		}
		if nextSessionID == "" {
			return "", errors.New("agent did not return a session ID")
		}
		fmt.Println("\nSession:", nextSessionID)
		return nextSessionID, nil
	}
	sessionID, err := execute("Read shipments.csv and write exceptions.md for the logistics team: delayed orders and their known reasons.", "")
	if err != nil {
		return err
	}
	if _, err := execute("The warehouse confirmed that order 1042 was picked up. Update exceptions.md and keep the other order details.", sessionID); err != nil {
		return err
	}
	report, err := sandbox.Files.ReadText(ctx, "/home/user/work/exceptions.md", "")
	if err != nil {
		return err
	}
	fmt.Println("exceptions.md\n" + report)
	return nil
}

func main() {
	if err := run(); err != nil {
		log.Fatal(err)
	}
}

In a text event, data holds a response fragment. tool_call announces a tool invocation. The end event contains sessionId and stopReason. The example accepts end_turn as normal completion and passes the returned ID to --resume. --session-id creates a new session with a chosen UUID. It does not resume an existing one.

Session history and files are stored in the sandbox. For another call, keep it and the session ID, or pause it. The full protocol and CLI options are described in the Grok Build reference.

Grok ​

Connect ​

Prepare a delivery summary ​

Events and session continuation ​

Grok

Connect

Prepare a delivery summary

Events and session continuation