agentport

Guide · Grok Build

Run Grok Build in Docker

xAI's Grok Build CLI runs in a Docker container. This guide uses a Dockerfile tested on 30 October 2026 with grok 1.0.70 on debian:bookworm-slim and Docker 29. It shows a headless sign-in, a volume that keeps the login, and a way to leave a long task running.

What you need

Step 1: Write the Dockerfile

Install Grok Build with curl -fsSL https://x.ai/cli/install.sh | bash. The script needs curl, bash and ca-certificates. It does not need Node.js, and it does not need to run as root. It puts the binary in ~/.grok/downloads/ and links it as ~/.grok/bin/grok, plus an agent alias. Config, the login (~/.grok/auth.json) and sessions also live in ~/.grok.

On Debian, a login shell (bash -l) resets PATH. Set PATH with ENV in the Dockerfile so a normal docker run finds grok. The image also installs git so the agent can work in a repository, and tmux for the long-running setup in step 5. The user dev is uid 1000. Running as non-root inside the container is the recommended default.

FROM debian:bookworm-slim
RUN apt-get update \
 && apt-get install -y --no-install-recommends curl ca-certificates git bash tmux \
 && rm -rf /var/lib/apt/lists/*
RUN useradd -m -s /bin/bash dev
USER dev
RUN curl -fsSL https://x.ai/cli/install.sh | bash
ENV PATH="/home/dev/.grok/bin:${PATH}"
WORKDIR /work
CMD ["grok"]

Step 2: Build the image and check it

docker build -t grok-build .
docker run --rm grok-build grok --version

The check prints a version line such as grok 1.0.70 (…).

Step 3: Sign in once with a device code

Mount a named volume on /home/dev/.grok. On first use Docker copies the image's ~/.grok, including the binary, into the empty volume. The login, sessions and the binary then survive container restarts.

  1. Run the login with a terminal attached. It needs -it. --device-code is an alias of --device-auth. 
    docker run --rm -it -v grok-home:/home/dev/.grok grok-build grok login --device-auth
  2. It prints To sign in, open this URL in your browser:, a link like https://accounts.x.ai/oauth2/device?user_code=XXXX-XXXX, the code, and Waiting for authorization....
  3. Open the link on any device and confirm the code. The command finishes when sign-in succeeds.

Step 4: Use it on a project

Mount the project on /work and start the image. That opens the Grok Build TUI in your project:

docker run --rm -it -v grok-home:/home/dev/.grok -v "$PWD":/work grok-build
The user inside the container is uid 1000. The folder you mount has to be writable by uid 1000. If it is not, run sudo chown -R 1000:1000 ./my-project, or build the image with your own uid.

Step 5: Keep it running

Use this for a long task, or when the container is on a server and you want to close your laptop. Start a detached container, then open Grok Build in tmux:

docker run -d --name grok --restart unless-stopped \
  -v grok-home:/home/dev/.grok -v "$HOME/projects/my-app":/work \
  grok-build sleep infinity
docker exec -it grok tmux new -A -s main grok

Detach tmux with Ctrl-b then d. Reattach later with the same docker exec line. tmux new -A attaches if the session already exists. The tmux session inside the container stays alive after docker exec exits. After a server reboot --restart unless-stopped brings the container back, but not the tmux session, so start it again with docker exec -it grok tmux new -A -s main grok -c. The -c flag continues the most recent Grok Build session for that folder.

Headless runs and CI

grok -p "prompt" (alias --single) runs one turn, prints to stdout and exits. --output-format accepts plain, json or streaming-json. --always-approve auto-approves tools. --permission-mode accepts default, acceptEdits, auto, dontAsk, bypassPermissions or plan.

For a script or CI job, set XAI_API_KEY to a key from console.x.ai. Grok uses that key when there is no signed-in session. A stored login takes precedence, so leave the grok-home volume unmounted when the key should be used. Pass --no-auto-update in scripts to skip update checks.

docker run --rm -e XAI_API_KEY -v "$PWD":/work grok-build grok --no-auto-update -p "Run the tests and fix any failure" --always-approve
--always-approve is much safer inside a throwaway container than on your own laptop. The agent can still change anything in the mounted folder and reach the network, so keep the project in git.

Editors and other clients can run the same agent over ACP (Agent Client Protocol) with grok agent stdio.

Updating grok

Rebuilding the image does not upgrade grok inside an existing volume. Docker copies ~/.grok from the image only when the volume is empty. After that, the volume's copy of the binary is the one that runs. Run grok update inside the container, or delete the volume and sign in again.

Security tips

Or skip the Dockerfile: AgentPort

AgentPort does this packaging for you. One install command starts a Docker container (ghcr.io/johnversus/agentport-node, amd64 and arm64) on your computer or VPS with Grok Build inside. It keeps your Grok login in ~/.grok on the host, so the login survives updates. The container opens a secure outbound link, binds to 127.0.0.1:8787 only, and you do not open any ports.

You get a chat for Grok Build in any browser, including your phone: approval buttons (Ask first / Auto / Always approve), several chats at once, chat history, a file tree and a git diff of changes. The browser connects straight to your server. AgentPort's cloud only handles sign-in and your list of computers. Google Antigravity works too. Codex CLI and Claude Code are not supported yet; they are on the roadmap.

The Free plan is 1 computer. Pro is $27/month for up to 3. You pay xAI for Grok yourself. Step-by-step install: Run Grok Build on your VPS. For why tmux only helps when it runs on a machine that stays on: Keep Grok Build running after you close your laptop.

FAQ

Why does grok say command not found in my container?

The binary is ~/.grok/bin/grok, which is not on Debian's default PATH. The Dockerfile sets PATH with ENV, so a normal docker run finds it. A login shell (bash -l) resets PATH and drops that directory, and the shell then reports command not found. Call /home/dev/.grok/bin/grok, or export PATH="/home/dev/.grok/bin:$PATH" first.

Where does Grok Build store its login in Docker?

In /home/dev/.grok inside the container. The login file is auth.json in that directory, next to config and sessions. Mount a named volume there (-v grok-home:/home/dev/.grok) and the login survives a new container.

Do I have to log in again after rebuilding the image?

No, if you keep the same volume. The login is in the volume, not in the image. Rebuilding also does not replace the grok binary stored in that volume. Run grok update inside the container to upgrade, or delete the volume and sign in again.

Can I use an API key instead of signing in?

Yes. Pass XAI_API_KEY (a key from console.x.ai) with -e. Grok uses it when there is no signed-in session. If a login is already stored in the mounted ~/.grok, that login is used instead.

Does AgentPort run Codex or Claude Code in Docker too?

Not yet. AgentPort runs Grok Build and Google Antigravity. Codex CLI and Claude Code are on the roadmap. Until then you can run them on a server yourself: Run Codex CLI and Claude Code on a VPS.

Try it on your own computer

The Free plan covers 1 computer. Pro is $27/month for up to 3. You bring the AI login and pay that provider directly.

Start free See pricing

More guides: Run Grok Build on your VPS and use it from your browser · Use Google Antigravity remotely from any device · Self-hosted AI coding agent on your own server with Docker · Use an AI coding agent from your phone · Keep Grok Build running after you close your laptop · Run Codex CLI and Claude Code on a VPS, and use them from your phone