Request early access

Tutorial

Tutorial: set up a project end to end

A complete walkthrough — from nothing to a working project with an AI assistant pointed at it. The example is a solo game project on one machine (the case that exercises the most of Grixel: big files, locking, an assistant). Adaptation notes call out what to change for a different stack or a team.

You'll run your own server here. If someone already runs one for you, skip to step 3 and use the address and token they gave you.

#The shape

Set up your user and access → start the server → log in → import your project → work → wire in the assistant. (Account and access setup edit config files directly, so they work whether the server is running or not; doing them first is just the simplest order.)

#1. One-time setup

Pick any namespace name for your work — this example uses mystudio. Create your user, mint a token, and grant yourself access in two commands:

DATA=~/grixel-data

# creates the data root, your user + token, and grants you read+write on /mystudio
grixeld user add -data-root $DATA -name me -grant /mystudio

# also give yourself admin on it (for locks and review sign-off)
grixeld acl grant -data-root $DATA me admin /mystudio

user add prints a token once — copy it now; you'll need it in step 3.

Adapt: onboarding a teammate later is one command — grixeld user add -data-root ~/grixel-data -name teammate -grant /mystudio. A running grixeld picks the new user and grant up automatically within a few seconds — no restart, and the fresh token logs straight in.

#2. Start the server

grixeld serve -data-root ~/grixel-data

It prints a banner with the exact command clients use to connect. Leave it running and open a new terminal for the rest.

Adapt (team): to let other machines connect, bind a reachable address and turn on TLS — see Hosting and backup. For solo on one machine the defaults (localhost, no TLS) are right.

#3. Log in

grixel login -server grpc://127.0.0.1:8090 -token <TOKEN>
grixel whoami          # -> me (remote: grpc://127.0.0.1:8090)

After this, every command uses your saved login automatically.

#4. Import your project

grixel init publishes the folder's files and turns it into your working copy. Add ignore presets for your stack so build artifacts never upload — combine them with commas. If your project is a git checkout, add git so its .git/ history doesn't get imported:

cd ~/path/to/mygame
grixel init -ref mystudio/games/mygame -m "initial import" -ignore godot,macos,git

Preview before you commit to it. A first import can be thousands of files — check exactly what would go up (and catch any folder you forgot to ignore) with the -n dry run, which uploads nothing:

grixel init -ref mystudio/games/mygame -m "initial import" -ignore godot,macos,git -n
# Dry run — 312 file(s), 240 MiB would be submitted (with the godot+macos+git preset applied):
#   art/            180 file(s)  210 MiB
#   scenes/          44 file(s)   18 MiB
#   ...
# Nothing was submitted. Add anything unwanted to .grixelignore and re-run — or drop -n to submit.

It groups by top-level folder, largest first, so a stray .git/, node_modules/, or build output is obvious. To eyeball individual files instead of the folder summary, add -v — it lists every file with its size (pipe it to a pager or grep for a big import). Adjust the ignores, re-run to re-check, then run the same command without -n to actually import. Swap godot for unity/unreal and add xcode/vscode if you use them; grixel ignore init lists all presets.

If a .grixelignore already exists, -ignore merges the preset's missing rules into it (keeping your own edits) rather than replacing it — so adding git on a later run correctly excludes nested .git/ folders too. Re-running is safe; nothing is duplicated.

grixel status works in this folder now.

#5. The everyday loop

grixel status                          # what changed; are you behind head
grixel diff                            # line diff for text (grixel difftool for a GUI)
grixel submit -m "tune spawn rates"    # commit (atomic)
grixel sync                            # pull others' changes (matters once it's not just you)

Binary assets get a lock. Code and text merge cleanly, but art, levels, and audio can't be merged. Claim an un-mergeable file before you open it so no one collides on it:

grixel edit art/characters/hero.psd    # exclusive lock; auto-released when you submit
grixel submit -m "block out the hero"

You never do this for code — just edit and submit. Even for binaries submit auto-claims the lock; grixel edit up front is the safe habit that surfaces a collision at the start instead of after you've done the work. See Large files and locking.

#6. Point Claude Code at the project

grixel mcp setup       # writes .mcp.json so the assistant can read the project (read-only)
grixel mcp preview      # shows exactly what the assistant will be able to see

Install the skill so Claude Code knows how to drive Grixel. The distribution ships a helper that does this for any assistant (Claude Code, Codex, opencode) and prints the connector wiring:

~/grixel-dist/skills/agent-setup.sh --tool claude .
# or, by hand:
mkdir -p .claude/skills && cp -R ~/grixel-dist/skills/claude-code/grixel .claude/skills/grixel

Then run claude in the folder. The skill activates on its own in a Grixel checkout and follows the rules — read over the connector, change through the CLI, lock binaries first, and tag its own commits as AI-assisted. grixel mcp preview is worth a look: it shows the whole surface the assistant gets, and that it has no write tools. More in Working with AI assistants.

#7. Grow into it

  • Branching — try changes on the side and merge them back: Branching.
  • Review and sign-off — require approval before something reaches a protected area: Review and sign-off.
  • Jobs — track the work next to the files: Jobs.
  • Keep the server running and backed up: Hosting and backup.

#Things worth knowing

  • Most operator commands work beside a live server. user add and acl grant/revoke edit the config files directly; a running grixeld applies the change automatically within a few seconds (or send it SIGHUP to apply immediately). backup -online, checkpoint, verify and gc run against a live server too — routine maintenance never means downtime. The ones that still need the server stopped are restore, compact, migrate and acl reload, none of which are routine. Client commands always run against the live server.
  • "not found" means "no access", not a bug. If a user can't see something, grant it: grixeld acl grant -data-root ~/grixel-data <user> rw /mystudio.
  • Back up ~/grixel-data — it is your entire depot. grixeld backup -online -data-root ~/grixel-data -out ~/grixel-backups works while the server runs, and every run after the first only copies what changed.