Your first spatial session

Pair one running Entity, one human relationship, and one WebXR shell.

Complete the terminal quickstart first. You need Node.js 22+ for the spatial workspace. Run these commands from the application checkout, not the documentation repository.

1. Install and build the spatial workspace

   npm run ar:install
   npm run ar:build
   
2. Pair your Entity and shell

   uv run ngram ar setup rook --target local
   

   Replace rook with your Entity’s config identifier. The wizard connects an Entity bridge, human identity, and shell. Its default shell path is ngramAR/shells/<entity>.

   To select a specific existing shell:

   uv run ngram ar setup rook --target local --shell ngramAR/shells/rook
   

   Follow the generated instructions and keep the canonical Entity process running. Shell configuration does not itself run the Python Entity.

3. Start the browser surface

   npm run ar:dev -- shells/rook
   

   Open the local URL printed by the command, normally http://localhost:3000.

4. Try a spatial action

   Ask the Entity:

   Inspect your current surface, wave hello, then place a small periwinkle cube in front of us.

   Confirm the inspection describes your actual session, the gesture plays, and a geometric cube appears. The expected tools are ar_inspect_surface, ar_gesture, and ar_spawn_object.

For the new creation tools, open Objects → Examples to try a kinetic workshop or resonance garden. Continue with Creations, Blender, and Programs to build and operate your own objects.

Share an existing relationship

If you already talk to the Entity in Telegram, send /whoami there. Use the returned person identifier when pairing AR:

uv run ngram ar setup rook --target local --person-id <your-person-id>

Replace the bracketed value with your own identifier and keep it in local configuration. Do not publish real user IDs in examples or shared shell files.

Enter a headset session

For a supported headset on a trusted LAN, the integrated Quest lab workflow handles hosted inference checks and the HTTPS spatial surface:

uv run ngram lab up rook --lan

For a manual setup, the spatial CLI supports a LAN host:

npm run ar:dev -- shells/rook --host 0.0.0.0

Use the printed HTTPS network URL on the headset. A localhost URL on the headset refers to the headset itself, not your development computer.

Stop and resume

Use the surface’s stop control or a direct “stop” request to cancel the active spatial turn. Closing a tab disconnects that surface; it does not stop a separate Entity worker. Use Ctrl+C for a foreground launcher, and see runtime stop controls for unattended processes.