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:

{
  "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:

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

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

grok

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

export XAI_API_KEY="xai-..."
grok

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

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:

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

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

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

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

Get SuperGrok or X Premium+

Modes available

See Agent Authentication for what each mode does and how to switch between them.

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.