Beginnen met Grok Build

Grok Build is de terminalgebaseerde code-agent van xAI. De agent leest bestanden, past code aan en voert commando’s uit op de computer waarop je hem start. Op een VPS of OpenStack-instance gebruik je Grok in een Linux-ontwikkelomgeving die ook beschikbaar blijft wanneer je laptop uitstaat.

In deze handleiding installeer en configureer je Grok Build op een Linux-server. Heb je een Grok-VPS met de agent voorgeïnstalleerd besteld? Dan sla je de installatie over en begin je bij de authenticatie. Je gebruikt Grok via SSH, met je Grok-account, een xAI API-key of een zelf gehost model via Ollama.

Waarom een GPU niet vereist is voor Grok Build

Bij gebruik van een xAI-model verwerkt xAI de input en output. Je server biedt de terminal, bestanden en ontwikkeltools. Een GPU is daarvoor niet nodig. Die wordt pas relevant als je ook zelf een model op dezelfde server draait.

De benodigde CPU-capaciteit, RAM en opslag hangen vooral af van je project. Builds, tests, containers en grote repositories gebruiken vaak meer resources dan de agent zelf. Een repository is een project waarin Git de bestanden en wijzigingsgeschiedenis bijhoudt.

Welke serverspecificaties heb ik nodig voor Grok Build?

Gebruik voor een klein ontwikkelproject met een extern model bijvoorbeeld twee vCPU’s en vier GB RAM als startpunt. Dit is een praktische richtlijn, geen officiële minimumvereiste. Kies extra capaciteit als je project zwaardere tests, builds of aanvullende diensten gebruikt.

• Bij een model van xAI kies je de servercapaciteit op basis van de lokale ontwikkeltaken.
• Bij Ollama op een andere server blijfven de resources die de modellen nodig hebben op die andere server. Je Grok-server heeft een verbinding met de modelserver nodig.
• Bij Ollama op dezelfde server moet ook het model in het beschikbare geheugen passen. De modelgrootte, quantisatie en contextlengte bepalen de extra RAM- of GPU-geheugenbehoefte. Quantisatie verkleint de precisie en daarmee doorgaans het geheugengebruik van modelgewichten.

Grok Build handmatig installeren

Stap 1

Verbind met je server via SSH of de VPS-console. Gebruik een normale Linux-user voor Grok. Voer root- en sudo-commando’s voor systeembeheer vanuit een beheersessie uit.

Stap 2

Werk vanuit een beheersessie met sudo-rechten de server bij en installeer de hulpmiddelen voor deze handleiding:

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

curl downloadt de installer, ca-certificates levert vertrouwde certificaten voor HTTPS, Git beheert projectbestanden, tmux houdt terminalsessies actief en nano is de teksteditor voor configuratiebestanden. -y bevestigt de package-acties automatisch. Installeer daarnaast de buildtools die je eigen project vereist. Ga daarna terug naar de sessie van je normale Grok-user.

Stap 3

Installeer Grok Build met de officiële installer, onder je eigen user en zonder sudo:

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

De curl-opties stoppen bij HTTP-fouten, tonen eventuele foutmeldingen en volgen redirects. Het gedownloade script wordt direct uitgevoerd door Bash. Gebruik hiervoor alleen de officiële installer; bekijk het script vooraf als je de wijzigingen wilt controleren.

Stap 4

Herlaad je Bash-instellingen en controleer de installatie:

source ~/.bashrc
command -v grok
grok version

command -v toont het pad naar de executable. De installer gebruikt standaard ~/.grok/bin. Verschijnt geen pad? Volg de PATH-instructie uit de installer of log opnieuw in via SSH. PATH is de lijst met directories waarin je shell commando’s zoekt.

Grok-onboarding en authenticatie

Stap 1

Verbind via SSH met je server als de Linux-user waaronder je Grok gebruikt. Gebruik je een server met Grok voorgeïnstalleerd? Dan wordt je gevraagd om je wachtwoord eerst te wijzigen. Na het wijzigen van je wachtwoord wordt de verbinding met je server verbroken. Verbindt in dat geval opnieuw.

*** 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:

Stap 2

Als je een server met Grok voorgeïnstalleerd gebruikt, krijg je een prompt te zien om in te loggen in een browser en een een code in te voeren om te authenticeren met je Grok-account. Voer dit uit en ga verder met stap 3. 

Gebruik je een API-key? Onderbreek dan het proces met ctrl + c, configureer de 

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...

Maak een projectdirectory en open een blijvende terminalsessie:

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

-p bij mkdir maakt ook ontbrekende bovenliggende directories aan. -s geeft de tmux-sessie de naam grok. Ontbreekt tmux op de voorgeïnstalleerde server? Installeer het met sudo apt -y install tmux.

Stap 3

Gebruik de device-authenticatie om vanaf een server zonder browser in te loggen:

grok login --device-auth

--device-auth toont een URL en inlogcode. Open de getoonde URL in de browser op je eigen computer, voer je eigen code in en voltooi de authenticatie. Deel deze code niet. Gebruik als alternatief de API-keyroute in het volgende hoofdstuk.

Stap 4

Start Grok met een sandbox voor normale development-taken:

grok --sandbox workspace

--sandbox workspace beperkt schrijven tot je werkdirectory, ~/.grok/ en tijdelijke directories. Lezen buiten je project en netwerktoegang blijven toegestaan. Het profiel verbergt credentials niet automatisch.

Typ bijvoorbeeld: ‘Leg uit hoe dit project is opgebouwd. Wijzig nog geen bestanden.’ Beoordeel daarna de voorgestelde acties voordat je toestemming geeft voor wijzigingen of commando’s.

Grok gebruiken met een API-key

Een API-key is een alternatief voor accountauthenticatie. Maak de key aan in de xAI-console en controleer daar de API-toegang, gebruikslimieten en facturatie van je account.

Voer de volgende commando’s uit om je API-key te configureren voor Grok:

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

• read vraagt de key op zonder deze op het scherm te tonen 
• -r behandelt backslashes letterlijk
• -s verbergt je invoer
• -p toont de invoerprompt
• export maakt de key beschikbaar voor Grok en andere processen die je vanuit deze shell start. 

De echte key staat hierdoor niet in het ingevoerde shellcommando of de shellgeschiedenis.

Verwijder de variabele nadat je Grok hebt afgesloten:

unset XAI_API_KEY

Dit verwijdert de key niet uit processen die al gestart zijn en trekt de key niet in bij xAI. Gebruik voor permanente automatisering een secretvoorziening met beperkte toegang. Lees hiervoor onze handleiding over veilig met credentials omgaan in Linux.

Verwijder eerder opgeslagen accountauthenticatie met:

grok logout

Uitloggen verwijdert geen API-key die nog als omgevingsvariabele is ingesteld.

Ollama gebruiken met Grok Build

Met Ollama gebruik je een zelf gehost model als backend voor de agent. Grok Build blijft de interface en uitvoerder, maar het geselecteerde model verwerkt je prompts. Dit is niet hetzelfde als een actueel Grok-model van xAI lokaal draaien.

Installeer Ollama eerst volgens onze handleiding ‘Een LLM lokaal hosten met Ollama’, of neem apart een VPS met Ollama af. Kies een model met ondersteuning voor tool calling; niet ieder model ondersteunt tool calling en doorgaans zijn grotere, zwaardere modellen beter in het herkennen van of ze wel of niet een tool moeten gebruiken, zelfs wanneer die ondersteuning in een kleiner model is ingebouwd.

Stap 1

Verbind via SSH met je Grok-server. Voor dit voorbeeld draait Ollama op dezelfde server.

Stap 2

Controleer de geïnstalleerde modellen:

ollama list

Noteer de exacte modelnaam. Controleer ook welke contextlengte je Ollama-server daadwerkelijk gebruikt. Die bepaalt hoeveel gesprek en projectinformatie het model tegelijk verwerkt.

Stap 3

Open de Grok-gebruikersconfiguratie:

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

Voeg het volgende modelblok toe. Vervang JOUW_MODELNAAM door de naam uit ollama list en 32768 door de contextlengte die je endpoint gebruikt:

[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 een dummywaarde, geen geheim of authenticatie voor standaard lokaal Ollama. Het per-model veld voorkomt dat een xAI-accounttoken als fallback bij dit lokale endpoint terechtkomt. Gebruik echte credentials als je een eigen beveiligde proxy voor Ollama hebt.

Grok gebruikt de OpenAI-compatibele Chat Completions-API van Ollama. De sleutel ollama-local is je eigen modelalias. Voeg een bestaand blok met die naam niet nogmaals toe; werk het bij. Sla op en sluit nano met Ctrl + X > Y > Enter.

Stap 4

Controleer de configuratie en start met het lokale model:

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

-m selecteert de modelalias uit je zojuist gemaakte configuratie

Test eerst een korte opdracht zonder bestandswijzigingen. Foutmeldingen over tools, modelnamen of contextlengte wijzen op een incompatibiliteit of een afwijkende endpointconfiguratie.

Ollama op een andere server

Draait Ollama op een andere server? Gebruik in base_url het adres van een beveiligde private verbinding of een lokale SSH-tunnel naar die server. Houd /v1 aan. Maak de onbeveiligde Ollama-poort 11434 niet publiek bereikbaar.

De officiële handleiding voor custom modellen beschrijft de modelvelden, credentialkeuze en endpointconfiguratie.

Handige Grok-commando’s

Sessies starten en hervatten

Start een interactieve sessie in je projectdirectory:

grok --sandbox workspace

Hervat de meest recente sessie voor de huidige directory:

grok --sandbox workspace --continue

--continue laadt het vorige gesprek. Gebruik --resume met een session ID om een specifieke sessie te kiezen. Grok slaat gesprekken en bijbehorende gegevens standaard onder ~/.grok/sessions/ op.

Modellen kiezen

Toon de beschikbare modellen:

grok models

Selecteer een model bij het starten en vervang MODEL_ID door een naam uit het overzicht:

grok --sandbox workspace -m MODEL_ID

Gebruik binnen de interactieve sessie /model om het actieve model te wijzigen. Beschikbaarheid en ondersteunde functies hangen af van je account, provider en geïnstalleerde Grok-versie.

Grok niet-interactief uitvoeren

Voer één opdracht uit zonder de interactieve interface:

grok --sandbox read-only -p "Vat de structuur van deze repository samen. Wijzig geen bestanden."

-p geeft één prompt mee
read-only beperkt bestandswijzigingen tot Grok-state en tijdelijke bestanden en blokkeert netwerktoegang voor childprocessen op Linux. Model input/requests en ingebouwde webtools vallen niet onder die childprocessbeperking. Het profiel is dus geen offlinegarantie.

Je kunt de output van Grok laten verwerken in een JSON-object:

grok --sandbox read-only -p "Vat de repositorystructuur samen." --output-format json

--output-format json levert één JSON-object aan het einde
streaming-json levert afzonderlijke gebeurtenissen tijdens de uitvoering.

Geef scripts expliciete, beperkte toolrechten en controleer exitcodes en output. Gebruik geen algemene automatische goedkeuring om een geblokkeerde actie te omzeilen.

Commando’s binnen een Grok-sessie

Voer deze slashcommando’s in de interactieve Grok-interface in, niet in de Linux-shell:

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

• /help toont beschikbare opdrachten.
• /plan begint met een plan
• /model kiest het model
• /session-info toont sessiegegevens.
• /context toont contextgebruik
• /compact vat het gesprek samen
• /resume hervat een gesprek
• /new begint een nieuw gesprek
• /skills en /plugins openen het extensieoverzicht
• /settings opent de Grok-instellingen
• /quit sluit Grok af

Skills en plugins gebruiken

Een skill bevat herbruikbare instructies en eventueel scripts of referentiebestanden. Een plugin bundelt bijvoorbeeld skills, hooks of extra tools. Hooks voeren scripts uit bij gebeurtenissen in een sessie. Installeer alleen extensies waarvan je de herkomst en inhoud vertrouwt.

Grok herkent automatisch de configuratie en extensies die het tot zijn beschikking heeft. Bekijk de gevonden configuratie en extensies via:

grok inspect
grok plugin list

Grok ontdekt skills onder meer in .grok/skills/ in je project en ~/.grok/skills/ voor je user. Open /skills of /plugins binnen Grok om het extensieoverzicht te gebruiken. Controleer na wijzigingen met grok inspect welke onderdelen je project daadwerkelijk laadt.

Volg voor de installatie van skills en plugins de officiële handleiding voor skills, plugins en marketplaces. Een marketplace is een bron van extensies; opname daarin is geen garantie dat een plugin veilig is.

Grok veilig op een server gebruiken

Stap 1

Gebruik een afzonderlijke Linux-user voor je ontwikkelwerk. Heb je alleen een root-account? Maak vanuit een beheersessie eerst een normale user aan:

sudo adduser grokuser
sudo -iu grokuser

Voer deze opdrachten uit als beheerder; bij een root-shell is sudo niet nodig. -i opent een login-shell en -u kiest de user. Voeg grokuser niet standaard aan de sudo-groep toe. Installeer benodigde systeempackages vanuit je beheersessie en installeer Grok zelf onder grokuser. Een installatie in de homedirectory van een andere user is niet automatisch beschikbaar voor dit account.

Stap 2

Gebruik een eigen projectdirectory en leg projectspecifieke afspraken vast:

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

Voeg bijvoorbeeld het volgende toe en pas het aan je project aan:

# 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 leest AGENTS.md als projectinstructie. Dit is een instructie voor de agent, geen technische toegangsbeperking. Controleer de geladen instructies met grok inspect.

Aanvullende tips

• Start met het sandboxprofiel en behoud de standaard goedkeuringen voor toolacties. De sandbox beperkt technische toegang; goedkeuringen bepalen welke acties worden uitgevoerd. Op Linux gebruikt Grok hiervoor Landlock, een beveiligingsfunctie van de kernel.
   
• Stopt Grok met een melding dat de sandbox niet beschikbaar is? Controleer je kernel en omgeving volgens de sandboxdocumentatie. Los de oorzaak op voordat je verdergaat; schakel de sandbox niet uit om de melding te onderdrukken.
   
• Laat always-approve uitgeschakeld op een normale ontwikkelserver. Deze modus slaat de toolgoedkeuring over, maar bepaalt niet op zichzelf het sandboxprofiel. Lees hier meer over in de documentatie over Grok-permissions.
   
• Houd productiegegevens, SSH-private-keys en credentials buiten het account van de agent. Een afzonderlijke projectdirectory en .gitignore zijn geen beveiligingsgrens. Beperk externe integraties tot de rechten die je taak nodig heeft en controleer wijzigingen met Git voordat je ze commit of deployt.

git status
git diff

Deze commando’s gelden voor een bestaande Git-repository. git diff toont wijzigingen aan bijgehouden bestanden; bekijk nieuwe bestanden uit git status ook afzonderlijk.

Grok bijwerken en problemen oplossen

Controleer de geïnstalleerde versie en vraag de lokale help op:

grok version
grok --help

Controleer eerst of er een update beschikbaar is:

grok update --check

--check controleert alleen. Werk een installatie via de officiële installer bij met:

grok update

Sluit actieve sessies af vóór het bijwerken. Start daarna een nieuwe sessie of hervat je gesprek vanuit dezelfde projectdirectory.

Onderzoek configuratieproblemen met:

grok inspect

Dit toont welke instellingen, instructies en extensies Grok voor je directory vindt. Bij authenticatiefouten log je opnieuw in of controleer je de API-key bij xAI. Bij een onbekend model vergelijk je de naam met grok models of met de modellen van je eigen endpoint. Verwijder gevoelige gegevens voordat je diagnostische output deelt.

Bekijk de officiële CLI-referentie voor verdere opties.

In deze handleiding heb je Grok Build op een Linux-server geïnstalleerd of je voorgeïnstalleerde Grok-VPS geconfigureerd. Met een eigen Linux-user, expliciete sandbox en tmux gebruik je de agent voor ontwikkelwerk en hervat je gesprekken vanaf een andere computer.