# Grok (https://tenki.cloud/docs/sandbox/grok)

> For the complete documentation index, see [llms.txt](https://tenki.cloud/llms.txt)

Start from Tenki's pre-built Grok image and run xAI's coding agent headlessly.

Tenki's public `tenki/grok:stable` image starts from the standard [`sandbox` base image](https://tenki.cloud/docs/sandbox/base-image.md) and adds xAI's Grok Build coding agent (the `grok` command) plus the `grok-smoke` command for the API-key path. No credential is baked into the image. Grok Build authenticates two ways and both work in a sandbox: an `XAI_API_KEY` from [console.x.ai](https://console.x.ai) passed per session, or a device-code login against your X account. The key is the better default here, since nothing has to be approved by hand and a session can start and finish unattended. Sandbox usage is programmatic, so you drive grok headlessly with `-p`.

## Grok Build: an agentic coding agent in your sandbox

Grok Build is xAI's agentic terminal coding agent. It runs an autonomous coding agent right in the session, with plan-first execution so you see the plan before it acts. It can fan out to parallel sub-agents working in isolated git worktrees, supports the Model Context Protocol (MCP) natively, and offers a headless mode (`-p`) suited to CI and programmatic use.

## Start a session with an API key

Export an xAI API key locally, then pass it only to the session:

```bash
export XAI_API_KEY=<your-xai-api-key>

tenki sandbox create \
  --image tenki/grok:stable \
  --env "XAI_API_KEY=$XAI_API_KEY" \
  --name grok-demo
```

The shell history contains the environment variable reference, not the key value. Do not add the key to a template, snapshot, source file, or image.

Run the built-in connectivity check:

```bash
tenki sandbox exec --session grok-demo -- grok-smoke
```

`grok-smoke` runs one headless `grok -p` prompt with your `XAI_API_KEY` and checks the reply. A successful result looks like:

```text
TENKI_SANDBOX_OK
```

`grok-smoke` exits `2` when `XAI_API_KEY` is unset and `1` when the headless run fails.

Terminate the Tenki session when you finish:

```bash
tenki sandbox terminate grok-demo
```

## Start a session with a device-code login

Use this path to bill against a SuperGrok or X Premium+ subscription instead of an API key. Create the session with no key:

```bash
tenki sandbox create --image tenki/grok:stable --name grok-demo
```

Then start the device-code login. Pass `--stream` so the code reaches your terminal while the command is still waiting:

```bash
tenki sandbox exec --session grok-demo --stream -c 'grok login --device-auth'
```

Grok prints a URL and a short code, then blocks:

```text
To sign in, open this URL in your browser:

  https://accounts.x.ai/oauth2/device?user_code=XXXX-XXXX

Confirm this code in your browser:

  XXXX-XXXX

Waiting for authorization...
```

Open that URL on your own machine, confirm the code, and the command returns `✓ Signed in as <you>`. Grok is then authenticated for the life of the session, and `grok -p` runs with no `XAI_API_KEY` set.

Plain `grok login` does not work in a sandbox. It serves its OAuth redirect on a loopback port inside the guest, which your browser cannot reach. Use `--device-auth`.

## Run a headless task

Drive grok programmatically with the `-p` flag, which runs a single prompt and exits. For anything beyond `-p`, run `grok --help` inside the session or see [Grok Build's documentation](https://docs.x.ai/build/overview).

```bash
# One-shot task against the working directory inside the session
tenki sandbox exec --session grok-demo -- grok -p "summarize this repo's build setup"

# Against your own project: clone it into the session first, then run grok inside it
tenki sandbox exec --session grok-demo -- \
  bash -lc "git clone https://github.com/your-org/your-repo /home/tenki/work && cd /home/tenki/work && grok -p 'list the top-level modules and how they build'"
```

## Pin an exact build

`stable` moves to each newly published build. When a workload has to stay on the exact build it was tested against, resolve the tag once and launch the snapshot reference it returns:

```bash
tenki sandbox registry resolve tenki/grok:stable
# image_id    : ...
# snapshot_id : <uuid>

tenki sandbox create --image tenki/grok@<uuid>
```

A snapshot reference never moves, so it keeps launching that build after `stable` advances.