> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ngram.space/llms.txt
> Use this file to discover all available pages before exploring further.

# Your first spatial session

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

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

<Steps>
  <Step title="Install and build the spatial workspace">
    ```bash theme={null}
    npm run ar:install
    npm run ar:build
    ```
  </Step>

  <Step title="Pair your Entity and shell">
    ```bash theme={null}
    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:

    ```bash theme={null}
    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.
  </Step>

  <Step title="Start the browser surface">
    ```bash theme={null}
    npm run ar:dev -- shells/rook
    ```

    Open the local URL printed by the command, normally `http://localhost:3000`.
  </Step>

  <Step title="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`.
  </Step>
</Steps>

## Share an existing relationship

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

```bash theme={null}
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](/deployment/quest-lab) handles hosted inference checks and the HTTPS spatial surface:

```bash theme={null}
uv run ngram lab up rook --lan
```

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

```bash theme={null}
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](/guides/usage-and-controls) for unattended processes.