# Grok Build Harness

The Grok Build harness adapter connects `HarnessAgent` to the
[Grok Build CLI](https://x.ai/cli) through the Agent Client Protocol (ACP).
The adapter delegates ACP installation, sessions, streaming, tools, and
lifecycle management to `@ai-sdk/harness-acp`.

<Note>
  Harness packages are **experimental**. Expect breaking changes between
  releases as this early API gets further refined.
</Note>

## Setup

<InstallPackages packages="@ai-sdk/harness @ai-sdk/harness-grok-build @ai-sdk/sandbox-vercel" />

The ACP harness installs the pinned Grok Build CLI inside the sandbox when the
first session starts.

## Import

```ts
import { createGrokBuild, grokBuild } from '@ai-sdk/harness-grok-build';
```

`grokBuild` is equivalent to `createGrokBuild()` with its default
configuration.

## Basic Usage

```ts
import { HarnessAgent } from '@ai-sdk/harness/agent';
import { grokBuild } from '@ai-sdk/harness-grok-build';
import { createVercelSandbox } from '@ai-sdk/sandbox-vercel';

const agent = new HarnessAgent({
  harness: grokBuild,
  sandbox: createVercelSandbox({
    runtime: 'node24',
    ports: [4000],
  }),
});

const session = await agent.createSession();

let exitCode = 0;
try {
  const result = await agent.stream({
    session,
    prompt: 'Check the test failures and fix the production code.',
  });

  for await (const part of result.stream) {
    if (part.type === 'text-delta') {
      process.stdout.write(part.text);
    }
  }
} catch (err) {
  exitCode = 1;
  console.error(err);
} finally {
  await session.destroy();
  process.exit(exitCode);
}
```

To use this agent, ensure environment variables include `VERCEL_OIDC_TOKEN`
for Vercel Sandbox and one of the variables listed under
[authentication](#authentication) for Grok Build.

## Adapter Settings

Use `createGrokBuild()` to configure the runtime:

```ts
const harness = createGrokBuild({
  auth: 'ai-gateway',
  model: 'grok-code-fast-1',
  port: 4001,
  startupTimeoutMs: 180_000,
});
```

Settings:

- `auth`: selects `auto`, `direct`, or `ai-gateway` authentication. The default
  is `auto`, which selects AI Gateway when Gateway credentials are present and
  direct xAI authentication otherwise.
- `model`: Grok model id selected through ACP. When omitted, Grok Build chooses
  its own default model.
- `port`: ACP bridge port override.
- `startupTimeoutMs`: maximum time to wait for the ACP bridge to start.

The adapter pins the Grok Build CLI and ACP launch command. These implementation
details cannot be overridden through `createGrokBuild()`.

## Authentication

By default, authentication is resolved from the host environment and forwarded
to the Grok Build process in the sandbox.

Supported environment variables:

- `VERCEL_OIDC_TOKEN`
- `AI_GATEWAY_API_KEY`
- `AI_GATEWAY_BASE_URL`
- `XAI_API_KEY`

With direct authentication, the adapter forwards `XAI_API_KEY`. With AI
Gateway, it supplies the Gateway credential as `XAI_API_KEY`, maps the Gateway
base URL ending in `/v1` to `GROK_XAI_API_BASE_URL` and
`GROK_MODELS_BASE_URL`, and sets `GROK_CLIENT_NAME` and
`GROK_CLIENT_VERSION` for client attribution.

Force a specific authentication route when both kinds of credentials are
available:

```ts
const directHarness = createGrokBuild({ auth: 'direct' });
const gatewayHarness = createGrokBuild({ auth: 'ai-gateway' });
```

## Sandbox

Grok Build runs inside the sandbox through `@ai-sdk/harness-acp`. It requires a
network sandbox with at least one exposed port, such as
`@ai-sdk/sandbox-vercel`:

```ts
const sandbox = createVercelSandbox({
  runtime: 'node24',
  ports: [4000],
});
```

The first session requires network egress so the ACP harness can install
`@xai-official/grok@0.2.111` inside the sandbox.

## Built-in Tools

The adapter maps these Grok Build built-ins to common harness tools:

- `bash` (`run_terminal_command`)
- `edit` (`search_replace`)
- `grep`
- `webSearch` (`web_search`)
- `write`

Other Grok Build tools remain available under their native names, including
`read_file`, `list_dir`, `todo_write`, `spawn_subagent`, `monitor`, workflow and
scheduler tools, and image-generation tools.

Grok Build does not advertise ACP session modes for its permission behavior.
When Grok sends an ACP permission request, the ACP harness applies the
configured Harness `permissionMode` based on the tool kind. Grok may handle
safe built-in operations internally without sending a permission request.

## Known Limitations

- ACP v1 does not expose model-step boundaries or per-step usage. The adapter
  infers boundaries and reports unknown per-step usage when Grok does not
  provide totals.
- ACP v1 has no portable manual compaction or mid-turn steering API.
- ACP v1 has no portable built-in tool filtering API. Filtering host tools is
  supported, but filtering Grok built-ins throws an unsupported-capability
  error.
- A changed host-tool catalog requires Grok Build to refresh its ACP MCP tool
  list. If the implementation retains stale tools, the turn fails explicitly.

## Related

- [HarnessAgent](/docs/ai-sdk-harnesses/harness-agent)
- [Harness tools](/docs/ai-sdk-harnesses/tools)
- [Harness adapters](/docs/ai-sdk-harnesses/harness-adapters)
- [Agent Client Protocol](/providers/ai-sdk-harnesses/acp)


## Navigation

- [Claude Code](/providers/ai-sdk-harnesses/claude-code)
- [Codex](/providers/ai-sdk-harnesses/codex)
- [Pi](/providers/ai-sdk-harnesses/pi)
- [OpenCode](/providers/ai-sdk-harnesses/opencode)
- [Deep Agents](/providers/ai-sdk-harnesses/deepagents)
- [Agent Client Protocol](/providers/ai-sdk-harnesses/acp)
- [Grok Build](/providers/ai-sdk-harnesses/grok-build)


[Full Sitemap](/sitemap.md)