Request early access

Docs

Running a Grixel server

Everything in Grixel lives on a server called grixeld. Most people are handed a server address by whoever runs it — but if that's you, this page gets one running. You can do all of this on your own machine; a single server on one host is a perfectly good setup to start with.

grixeld was installed alongside grixel when you installed Grixel.

#1. Start the server

The server keeps everything in one folder, called the data root. Pick a location and start it:

grixeld serve -data-root ~/grixel-data

That's it — the server is now running and listening for clients (by default on localhost:8090). On startup it prints a short banner with the exact command a client uses to connect, for example:

grixeld ready — data root: /home/you/grixel-data
  connect a client:  grixel login -server grpc://127.0.0.1:8090 -token <token>
  create a token:    grixeld user add -data-root /home/you/grixel-data -name <name>
  listening:  grpc://127.0.0.1:8090 (gRPC, primary)  http://127.0.0.1:8080 (HTTP fallback)

Copy that -server URL when you connect clients. It runs in the foreground; press Ctrl-C to stop it. To keep it running properly in the background, see Hosting and backup.

The data root is created on first use and holds all your files, history, and settings. Back it up (see the hosting page); losing it loses everything.

#2. Create users and hand out tokens

People sign in with a token. Create a user and mint one. These are offline commands, so stop the server first (Ctrl-C), run them, then start it again:

grixeld user add -data-root ~/grixel-data -name alice

This prints a token once — copy it and give it to that person; it can't be shown again. Give yourself an administrator account too (any name; system is a common choice for the operator).

Useful options:

grixeld user add -data-root ~/grixel-data -name ci-bot -scope ro -ttl 90d
  • -scope ro makes a read-only token (good for bots that only need to read).
  • -ttl 90d makes the token expire after a while (e.g. 12h, 30m, 90d).

List users, or roll a token if one leaks:

grixeld user list   -data-root ~/grixel-data
grixeld user rotate -data-root ~/grixel-data -name alice

#3. Decide who can see what

A fresh server starts locked down: the operator (system) can see everything, and everyone else has no access until you grant it. So a brand-new user you just created will see nothing — that's expected, not a bug. You grant access from the command line, no file editing required (these are offline commands, so stop the server first, then start it again):

# grant a user read+write on a path
grixeld acl grant -data-root ~/grixel-data alice rw /companies/acme/games/seasonal

# read-only, or full admin, on a path
grixeld acl grant -data-root ~/grixel-data ci-bot   read  /companies/acme
grixeld acl grant -data-root ~/grixel-data alice    admin /companies/acme/games/seasonal

Even simpler — create a user and grant them access in one step (perfect for onboarding a tester):

grixeld user add -data-root ~/grixel-data -name tester -grant /companies/acme

To take access away, grixeld acl revoke with the same arguments. Check how a path resolves for someone:

grixeld acl explain -data-root ~/grixel-data -as alice /companies/acme/games/seasonal

How the rules work: access is read, write, or admin; the most specific path wins (a rule on /companies/acme/games/seasonal beats one on /companies/acme), and a deny overrides an allow at the same specificity. Anyone with no matching rule sees the path as not found — they can't even tell it exists. (See Sharing and visibility.)

The grants live in ~/grixel-data/.grixel/acl/main.yaml. You can edit that file by hand for advanced setups — groups (grant many people at once) and deny rules — then apply it with grixeld acl reload or by restarting:

groups:
  art-team: [alice, maya]
rules:
  - { subject: "group:art-team", action: write, path: /companies/acme/games/seasonal/art, effect: allow }

#4. Connect a client

On any machine (including this one), sign in with a token from step 2 and start working:

grixel login -server grpc://your-server-host:8090 -token <token>
grixel whoami

If the server is on the same machine, grpc://localhost:8090 is the address.

#Next

  • Getting started — create your first project against the server you just started.
  • Hosting and backup — keep it running, secure it for use beyond your own machine, and back it up.