Getting started with Grok Build

Grok Build is xAI’s terminal-based coding agent. The agent reads files, modifies code and runs commands on the computer where you launch it. On a VPS or OpenStackinstance, you can use Grok in a Linux development environment that remains available even when your laptop is switched off.

This guide explains how to install and configure Grok Build on a Linux server. Have you ordered a Grok VPS with the agent pre-installed? You can skip the installation and start with authentication. You can use Grok over SSH, with your Grok account, an xAI API key or a self-hosted model via Ollama.

Why a GPU is not required for Grok Build

When using an xAI model, xAI processes the input and output. Your server provides the terminal, files and development tools. A GPU is not needed for this. It only becomes relevant if you also run a model yourself on the same server.

The required CPU capacity, RAM and storage depend mainly on your project. Builds, tests, containers and large repositories often use more resources than the agent itself. A repository is a project in which Git tracks files and their change history.

What server specifications do I need for Grok Build?

For a small development project using an external model, two vCPUs and four GB of RAM are a reasonable starting point. This is a practical guideline, not an official minimum requirement. Choose more capacity if your project involves demanding tests, builds or additional services.

• When using an xAI model, choose your server capacity based on the local development tasks.
• When running Ollama on another server, the resources required by the models remain on that server. Your Grok server needs a connection to the model server.
• When running Ollama on the same server, the model must also fit into the available memory. The model size, quantisation and context length determine the additional RAM or GPU memory required. Quantisation reduces precision and generally reduces the memory used by model weights.

Installing Grok Build manually

Step 1

Connect to your server via SSH or the VPS console. Use a standard Linux user for Grok. Run root and sudo commands for system administration from an administrator session.

Step 2

From an administrator session with sudo privileges, update the server and install the tools used in this guide:

sudo apt -y update && sudo apt -y upgrade
sudo apt -y install curl ca-certificates git tmux nano

curl downloads the installer, ca-certificates provides trusted certificates for HTTPS, Git manages project files, tmux keeps terminal sessions running and nano is the text editor for configuration files. The -y option automatically confirms package operations. Also install any build tools your project requires. Then return to your standard Grok user session.

Step 3

Install Grok Build using the official installer, under your own user account and without sudo:

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

The curl options stop on HTTP errors, display error messages and follow redirects. Bash executes the downloaded script directly. Only use the official installer; inspect the script beforehand if you want to review the changes it makes.

Step 4

Reload your Bash settings and check the installation:

source ~/.bashrc
command -v grok
grok version

command -v displays the path to the executable. By default, the installer uses ~/.grok/bin. No path displayed? Follow the PATH instructions from the installer or log in again over SSH. PATH is the list of directories your shell searches for commands.

Grok onboarding and authentication

Step 1

Connect to your server over SSH as the Linux user under which you run Grok. If you use a server with Grok pre-installed, you will first be prompted to change your password. Once you have changed it, your connection to the server will be closed. If this happens, reconnect.

*** System restart required ***

  Grok Build
  ==========

  Usage:    grok

  Authentication options:
    - xAI account (a device code and URL are shown; open the URL on your own computer)
    - API key (export XAI_API_KEY=xai-...)

  Note: Grok can read and change any file the user running it can reach,
        and can use sudo if that user has it. Press Shift+Tab for Plan
        mode to review changes before they are applied.

  Docs:     https://docs.x.ai/build/overview


The programs included with the Ubuntu system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.

Ubuntu comes with ABSOLUTELY NO WARRANTY, to the extent permitted by
applicable law.

WARNING: Your password has expired.
You must change your password now and login again!
Changing password for transip.
Current password:
New password:
Retype new password:

Step 2

If you use a server with Grok pre-installed, you will be prompted to sign in through a browser and enter a code to authenticate with your Grok account. Complete this process and proceed to step 3. 

Using an API key? Interrupt the process with Ctrl + C, then configure the 

Installing Grok Build...
=============================================

Fetching latest stable version...
Installing Grok 1.0.52 (linux-x86_64)...
  Downloading grok 1.0.52...
  Binary linked to /home/transip/.grok/bin/grok and /home/transip/.grok/bin/agent.
Grok 1.0.52 installed to /home/transip/.grok/bin/grok
  Updated /home/transip/.grok/bin in PATH in /home/transip/.bashrc.

Restart your terminal, then run 'grok' or 'agent' to get started!

=============================================
 Starting Grok Build setup...
 A URL and a short code will appear below.
 Open the URL on your own computer and enter
 the code to sign in.
=============================================


To sign in, open this URL in your browser:

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

  (Could not open browser automatically — open the URL above manually.)

Confirm this code in your browser:

  RVCK-VTQ2

Only continue with a code you requested. Don't share it with anyone.

Waiting for authorization...

Create a project directory and start a persistent terminal session:

mkdir -p ~/projects/example-project
cd ~/projects/example-project
grok

The -p option for mkdir also creates any missing parent directories. The -s option names the tmux session grok. Is tmux missing from the pre-installed server? Install it using sudo apt -y install tmux.

Step 3

Use device authentication to sign in from a server without a browser:

grok login --device-auth

--device-auth displays a URL and sign-in code. Open the displayed URL in a browser on your own computer, enter your code and complete authentication. Do not share this code. Alternatively, use the API key method in the next section.

Step 4

Start Grok with a sandbox for normal development tasks:

grok --sandbox workspace

--sandbox workspace restricts writing to your working directory, ~/.grok/ and temporary directories. Reading outside your project and network access are still permitted. This profile does not automatically hide credentials.

For example, type: ‘Explain how this project is structured. Do not modify any files yet.’ Review the proposed actions before approving changes or commands.

Using Grok with an API key

An API key is an alternative to account authentication. Create the key in the xAI console and check your account’s API access, usage limits and billing there.

Run the following commands to configure your API key for Grok:

read -r -s -p 'xAI API-key: ' XAI_API_KEY
printf '\n'
export XAI_API_KEY
grok --sandbox workspace

• read prompts for the key without displaying it on screen 
• -r treats backslashes literally
• -s hides your input
• -p displays the input prompt
• export makes the key available to Grok and other processes started from this shell. 

This means the actual key does not appear in the shell command you entered or in your shell history.

Remove the variable after exiting Grok:

unset XAI_API_KEY

This does not remove the key from processes that are already running or revoke it with xAI. For permanent automation, use a secrets management solution with restricted access. See our guide to handling credentials securely in Linux.

Remove previously saved account authentication with:

grok logout

Logging out does not remove an API key that is still set as an environment variable.

Using Ollama with Grok Build

Ollama lets you use a self-hosted model as the agent’s backend. Grok Build remains the interface and execution tool, but the selected model processes your prompts. This is not the same as running a current xAI Grok model locally.

First install Ollama by following our guide ‘Hosting an LLM locally with Ollama’, or purchase a VPS with Ollama separately. Choose a model that supports tool calling. Not every model supports tool calling, and larger, more powerful models are generally better at recognising when to use a tool, even if a smaller model has built-in support for it.

Step 1

Connect to your Grok server over SSH. In this example, Ollama runs on the same server.

Step 2

Check the installed models:

ollama list

Make a note of the exact model name. Also check the context length your Ollama server actually uses. This determines how much conversation and project information the model can process at once.

Step 3

Open the Grok user configuration:

mkdir -p ~/.grok
nano ~/.grok/config.toml

Add the following model block. Replace JOUW_MODELNAAM with the name from ollama list and 32768 with the context length used by your endpoint:

[model.ollama-local]
model = "JOUW_MODELNAAM"
base_url = "http://127.0.0.1:11434/v1"
name = "Ollama lokaal"
api_backend = "chat_completions"
api_key = "ollama"
context_window = 32768

api_key = "ollama" is a dummy value, not a secret or authentication for a standard local Ollama instance. This per-model setting prevents an xAI account token from being sent to this local endpoint as a fallback. Use real credentials if you have your own secured Ollama proxy.

Grok uses Ollama’s OpenAI-compatible Chat Completions API. The key ollama-local is your own model alias. If a block with this name already exists, update it rather than adding it again. Save and exit nano using Ctrl + X > Y > Enter.

Step 4

Check the configuration and start Grok with the local model:

grok inspect
grok --sandbox workspace -m ollama-local

-m selects the model alias from the configuration you have just created

First test a short instruction that does not modify any files. Errors relating to tools, model names or context length indicate an incompatibility or a different endpoint configuration.

Ollama on another server

Is Ollama running on another server? Set base_url to the address of a secure private connection or a local SSH tunnel to that server. Keep /v1 in the URL. Do not expose the unsecured Ollama port 11434 to the public internet.

The official custom models guide describes the model settings, choice of credentials and endpoint configuration.

Useful Grok commands

Starting and resuming sessions

Start an interactive session in your project directory:

grok --sandbox workspace

Resume the most recent session for the current directory:

grok --sandbox workspace --continue

--continue loads the previous conversation. Use --resume with a session ID to select a specific session. By default, Grok stores conversations and associated data under ~/.grok/sessions/.

Choosing models

Display the available models:

grok models

Select a model at startup, replacing MODEL_ID with a name from the list:

grok --sandbox workspace -m MODEL_ID

Within an interactive session, use /model to change the active model. Availability and supported features depend on your account, provider and installed Grok version.

Running Grok non-interactively

Run a single instruction without the interactive interface:

grok --sandbox read-only -p "Summarise the structure of this repository. Do not modify any files."

-p passes a single prompt
read-only restricts file changes to Grok state and temporary files, and blocks network access for child processes on Linux. Model inputs/requests and built-in web tools are not subject to that child-process restriction. This profile therefore does not guarantee offline operation.

You can have Grok’s output returned as a JSON object:

grok --sandbox read-only -p "Summarise the repository structure." --output-format json

--output-format json produces one JSON object at the end
streaming-json produces individual events during execution.

Give scripts explicit, restricted tool permissions and check exit codes and output. Do not use blanket automatic approval to bypass a blocked action.

Commands within a Grok session

Enter these slash commands in Grok’s interactive interface, not in the Linux shell:

/help
/plan
/model
/session-info
/context
/compact
/resume
/new
/skills
/plugins
/settings
/quit

• /help displays available commands.
• /plan starts with a plan
• /model selects the model
• /session-info displays session information.
• /context displays context usage
• /compact summarises the conversation
• /resume resumes a conversation
• /new starts a new conversation
• /skills and /plugins open the extensions overview
• /settings opens the Grok settings
• /quit exits Grok

Using skills and plugins

A skill contains reusable instructions and may also include scripts or reference files. A plugin can bundle skills, hooks or additional tools. Hooks run scripts when events occur during a session. Only install extensions from sources you trust and whose contents you have reviewed.

Grok automatically detects the configuration and extensions available to it. View the detected configuration and extensions using:

grok inspect
grok plugin list

Grok discovers skills in locations including .grok/skills/ in your project and ~/.grok/skills/ for your user. Open /skills or /plugins within Grok to view available extensions. After making changes, use grok inspect to check which components your project actually loads.

To install skills and plugins, follow the official guide to skills, plugins and marketplaces. A marketplace is a source of extensions; being listed there does not guarantee that a plugin is safe.

Using Grok securely on a server

Step 1

Use a separate Linux user for your development work. If you only have a root account, first create a standard user from an administrator session:

sudo adduser grokuser
sudo -iu grokuser

Run these commands as an administrator; sudo is not required in a root shell. -i opens a login shell and -u selects the user. Do not add grokuser to the sudo group by default. Install the required system packages from your administrator session and install Grok itself under grokuser. An installation in another user’s home directory is not automatically available to this account.

Step 2

Use a dedicated project directory and document any project-specific rules:

mkdir -p ~/projects/example-project
cd ~/projects/example-project
nano AGENTS.md

For example, add the following and adapt it to your project:

# Project instructions

- Explain planned changes before editing files.
- Run the project's tests after code changes.
- Do not edit production secrets or deployment keys.
- Do not deploy or push changes without approval.

Sla op met Ctrl + X > Y > Enter. Grok reads AGENTS.md as project instructions. These are instructions for the agent, not a technical access restriction. Use grok inspect to check which instructions have been loaded.

Additional tips

• Start with the sandbox profile and retain the default approval prompts for tool actions. The sandbox restricts technical access; approvals determine which actions are executed. On Linux, Grok uses Landlock, a kernel security feature, for this.
   
• Does Grok stop with a message saying the sandbox is unavailable? Check your kernel and environment against the sandbox documentation. Resolve the cause before proceeding; do not disable the sandbox simply to suppress the message.
   
• Keep always-approve disabled on a normal development server. This mode skips tool approval but does not itself determine the sandbox profile. Read more in the documentation about Grok permissions.
   
• Keep production data, private SSH keys and credentials outside the agent’s account. A separate project directory and .gitignore are not security boundaries. Restrict external integrations to the permissions required for your task and review changes with Git before committing or deploying them.

git status
git diff

These commands apply to an existing Git repository. git diff displays changes to tracked files; also review new files shown by git status separately.

Updating Grok and troubleshooting

Check the installed version and display the local help:

grok version
grok --help

First check whether an update is available:

grok update --check

--check only checks for updates. Update an installation made with the official installer using:

grok update

Close active sessions before updating. Then start a new session or resume your conversation from the same project directory.

Investigate configuration issues using:

grok inspect

This shows which settings, instructions and extensions Grok detects for your directory. If authentication fails, sign in again or check your API key with xAI. If a model is unknown, compare its name with grok models or the models available from your own endpoint. Remove sensitive information before sharing diagnostic output.

See the official CLI reference for further options.

In this guide, you have installed Grok Build on a Linux server or configured your pre-installed Grok VPS. With a dedicated Linux user, an explicit sandbox and tmux, you can use the agent for development work and resume conversations from another computer.