# Grok (https://jackin.tailrocks.com/guides/authentication/agents/grok/)



Grok Build authenticates via `~/.grok/auth.json` on your host. In `sync` mode (the default), jackin' copies this entire file into the container on every launch — the Grok CLI inside the container uses the same credential lookup as on the host.

The file is a JSON object mapping scope URLs to credential records. A typical entry (from `grok login`) looks like:

```json
{
  "https://auth.x.ai::b1a00492-073a-47ea-816f-4c329264a828": {
    "key": "<JWT>",
    "auth_mode": "oidc",
    "refresh_token": "<refresh>",
    "email": "you@example.com",
    "user_id": "...",
    "team_id": "...",
    "expires_at": "...",
    ...
  }
}
```

The CLI (both on host and inside jackin') prefers a `GROK_DEPLOYMENT_KEY` environment variable when present; otherwise it reads the appropriate scope entry from `auth.json`.

The standard way to authenticate Grok on the host with an API key (non-browser) is:

```bash
export XAI_API_KEY="xai-..."
grok
```

(See the Grok docs for details.)

In jackin', when you select `api_key` mode for Grok (in the Auth tab or via `jackin config auth set api_key --agent grok`), jackin' will inject the configured value into the container under *both* `XAI_API_KEY` and `GROK_DEPLOYMENT_KEY`. This lets the in-container Grok CLI use whichever the deployment or personal key expects.

The CLI (and installer) prefers `GROK_DEPLOYMENT_KEY` when present (enterprise/managed setups can also deliver managed config and requirements); otherwise falls back to `XAI_API_KEY` or auth.json.

## Logging in on the host [#logging-in-on-the-host]

Before sync can forward anything, you need a working Grok login on your host:

```bash
grok
```

The first run opens a browser for authentication (SuperGrok or X Premium+ required). Alternatively, set the API key directly:

```bash
export XAI_API_KEY="xai-..."
grok
```

<Aside type="tip">
  To verify the host login is active, run `grok` briefly on the host — if it starts a session without prompting for credentials, you're good. For the key path, `echo $XAI_API_KEY` should be non-empty.
</Aside>

Running the installer or `grok` for the first time creates `~/.grok/auth.json` (the scoped credential store) along with `~/.grok/bin/grok` (and the `agent` symlink), `config.toml`, downloads cache, and shell completions. Only `auth.json` carries the authentication material that jackin' forwards.

## Binary in the container [#binary-in-the-container]

Grok Build is not pre-installed in the base construct image. Your role's Dockerfile (or the role's `jackin.role.toml` construct steps) must install the CLI, typically with the same command used on the host:

```dockerfile
RUN curl -fsSL https://x.ai/cli/install.sh | bash
```

Or vendor a pinned Linux binary for the target architecture and ensure it (and the `agent` symlink) is on `PATH` inside `/home/agent/.grok/bin` or `/home/agent/.local/bin`.

Once the binary is present, jackin' handles auth forwarding for `sync` and `api_key` modes.

## Runtime approvals [#runtime-approvals]

jackin' launches the `grok` binary with `--always-approve` by default (see the entrypoint in the construct image). This lets Grok perform edits and tool calls autonomously without interactive approval prompts inside the jackin' container, consistent with the "dangerous"/"yolo" modes used for Claude Code, Codex, Amp, Kimi, and OpenCode.

Plan mode (and other Grok-specific controls) can still be enabled explicitly via role hooks (`source.sh` / `preflight.sh`) or by passing flags (e.g. `--no-plan` is not forced; use `--permission-mode plan` etc. as needed).

Additional flags (e.g. `--sandbox`, `--rules`, `--system-prompt-override`, `--todo-gate`) can be passed via role hooks or extra arguments; they are appended after the defaults.

## Model selection [#model-selection]

If the role manifest declares a model for Grok (under `[grok] model = "..."`), jackin' passes it on the CLI using `-m` (or `--model`) for every launch of that agent. This is the mechanism for per-role model overrides (the CapsuleConfig models map feeds `agent_model_args`, which appends the flag to the entrypoint invocation, so the command becomes `grok ... -m <model>`).

Models are not written into `~/.grok/config.toml`; the CLI flag is used exclusively.

## Subscription [#subscription]

Grok Build is available to SuperGrok and X Premium+ subscribers.

**[Get SuperGrok or X Premium+](https://grok.com/supergrok)**

## Modes available [#modes-available]

| Mode             | Supported                                                                                 |
| ---------------- | ----------------------------------------------------------------------------------------- |
| `sync` (default) | Yes — forwards the entire `~/.grok/auth.json` (OIDC tokens, refresh tokens, profile info) |
| `api_key`        | Yes — injects `XAI_API_KEY`                                                               |
| `oauth_token`    | No — rejected at config time                                                              |
| `ignore`         | Yes — no forwarding                                                                       |

See [Agent Authentication](/guides/authentication/agents/) for what each mode does and how to switch between them.

## Troubleshooting [#troubleshooting]

If Grok inside the container shows it is not authenticated:

1. Check that the host login is active — run `grok` briefly on the host, or confirm `XAI_API_KEY` or `GROK_DEPLOYMENT_KEY` is configured for the Grok agent (in api\_key mode or explicit env) in the Auth tab / config. You can also inspect `cat ~/.grok/auth.json`.
2. Open the **Auth** tab in `jackin console` and verify the effective mode for the (workspace × role × Grok) cell.
3. If the container has stale credentials and the host has fresh ones, restart: `jackin eject <role> && jackin load <role>`.

When using api\_key mode for Grok, the configured value is injected under both env var names so the CLI can use personal or deployment-key auth as needed. For managed setups, `GROK_DEPLOYMENT_KEY` also enables fetching of deployment-specific managed\_config/requirements.