# Devices (https://docs.neuralisapp.com/getting-started/devices)

A **device** is a computer paired with a Neuralis host: the server's own
machine, or a member's laptop. The host reaches it — its folders as sources,
its shell for the `execute` tool and the terminal — through a small broker that
runs on the device and dials out to the host. Nothing on the device is
reachable until its owner says so, on that machine; no role in the app can
widen it.

The desktop app pairs its own computer from its **This computer** page; these are the steps by
hand, with the `neuralis` command ([CLI guide](https://docs.neuralisapp.com/getting-started/cli.md)).

## Pair this computer [#pair-this-computer]

Run on the machine itself:

```bash
npm install -g @neuralis/cli                                  # 1. the CLI (Node.js 22.22 or newer)
neuralis device pair --host https://neuralis.example.com      # 2. one consent in the browser
neuralis device install                                       # 3. the login service, the sandbox helper (Linux), an allowlist with no folder
neuralis device grant ~/projects                              # 4. let the app read a folder (--write to change it too)
```

`--host` is the address you open Neuralis at; the app keeps only a hash of the
device secret. On a server you run yourself, devices stay off until an admin
turns on **Devices: Kill-Switch** under Admin → Config: before that a device
pairs and its link connects, but the host runs nothing on it.

Step 3 proves the OS sandbox on the machine before any command
runs (see [the sandbox](#the-sandbox)). Repeat step 4 for every folder the app
may reach — beside the operating system's own program folders and the shared
temporary folder (`/tmp` on Linux), which a command may read, the allowlist denies
everything else. Step 3 adds one thing to run
(read and execute), never a data folder to read or write: the folders of the Node
and the CLI the device itself runs on, where the sandbox does not already reach
them, so a skill's script and `neuralis request` work in the sandbox; it prints
them, and a device that already has an allowlist keeps its own. Pairing is a person's act and
is refused inside a skill.

```bash
neuralis device status                 # pairing, allowlist, helper, link, readiness, pending requests
neuralis device run                    # the broker in the foreground instead of the service
neuralis device list --watch           # your devices as the app sees them, followed live
neuralis device grant ~/projects --revoke    # take a folder back
neuralis device grant --background     # allow background commands (up to an hour each); --revoke takes it back
```

The installed service keeps the link up: when the app restarts or the link
drops, the device dials again on its own, backing off up to one minute between
tries. A device the app refuses 30 times in a row (about half an hour) while the
app still answers stops dialling, and `neuralis device status` says so; pair it
again, or start it again once the app accepts it. A revoke, a disabled owner or
a sessions reset ends the link for good. `neuralis update --apply` restarts the
device service on the new command ([updating](https://docs.neuralisapp.com/getting-started/updating.md)).

## Who decides what [#who-decides-what]

| Decision | Who makes it | Where |
|---|---|---|
| Pair the computer with a host | the person who will own it (`device.own`) | on the machine: `neuralis device pair --host <url>` |
| Which folders a host may read or write | the device's owner | on the machine: `neuralis device grant <dir> [--write] [--host <url>]` |
| Whether other members may run commands in a folder | the device's owner | on the machine: `neuralis device grant <dir> --others exec` |
| Which members may use another member's device at all | the project's admins, through roles | the app: `exec.device` / `terminal.device` |
| Run without the OS sandbox | the device's owner, explicitly | on the machine: `neuralis device grant --unconfined` |
| The device's own sign-in and keys | nobody — no grant reaches them | fixed: the device folder (every host's link secret), the CLI sign-in folder, and the sandbox helper and service file when they live in your home |
| The Neuralis host's own data in the same home | nobody through a grant — your own commands keep the project folders and run installed packages | fixed: `app`, `projects`, `checkpoints`, `qdrant-backups`, `build` and `qdrant-version.json` in the device's data folder (`~/.neuralis` or `$XDG_DATA_HOME/neuralis`, `%USERPROFILE%\.neuralis`, or `NEURALIS_HOME`) |

The last two rows hold whatever you grant: a host's file requests never see those
paths, and commands run for other members never reach them, even when you open
your whole home (`neuralis device status` lists them). Your own sandboxed
commands and terminal never reach the device folder, or the host's keys,
users and backups, either — the host serves them through its own pages and
sources. Your own commands do reach the host's project folders (a computer that
runs the host itself runs your unconfined commands there), and they may run an
installed package the host names, never change it. `neuralis device grant`
refuses a folder inside any of that data. The CLI sign-in folder and the service file
stay reachable to your commands — they are yours. The protected data folder is
the one the device itself resolves: a host whose data lives in a folder the
device's environment does not name is not covered. The Node
and the Neuralis CLI the device runs, and its sandbox helper, are read-only to
every command and every file request, so even a whole-drive write grant cannot
replace the program that writes your folder list. On Windows a whole-drive grant
(`neuralis device grant C:\ --write`) works: commands reach the drive's existing
files and folders and may create new top-level folders, while Windows itself
refuses a new file directly under `C:\` as it does outside the sandbox. An entry
created directly under the drive root after a command started is not reachable
from that command. Running unconfined removes
this protection with the sandbox.

A device belongs to whoever paired it. Using your own device in a project takes
the `device.own` feature — the member role holds it, and an admin can grant it
to any other role, a viewer invited through a link included. Another member's
device needs `exec.device` (commands) or `terminal.device` (a terminal tab),
and the device must be running sandboxed.

## Folders are per host [#folders-are-per-host]

Every folder grant names ONE host. A computer paired with your company's host
and with your own home server gives each only the folders you granted to it:
the host is identified by the link it dials in on, so one host can never reach
a folder you gave another — whatever it asks for.

```bash
neuralis device grant ~/work --host https://company.example.com          # the company host reads ~/work
neuralis device grant ~/notes --write --host https://home.example.com    # the home host reads and writes ~/notes
neuralis device grant ~/work --host https://company.example.com --revoke # take it back
```

With one host paired, `--host` can be left out. With several it is required —
there is no "every host" form. A toolchain root (`--exec`, for example
`~/.nvm`) is the machine's: it is added read-only to every command, for every
host, and it opens no folder for reading. `neuralis device status` suggests the
ones the sandbox cannot reach yet.

Each host also sees only its own terminals, background commands and pending
folder requests on the device: it cannot list, attach to or end what another
host started. Your own `neuralis device status` on the machine shows them all.

## Other members' commands [#other-members-commands]

By default a folder runs commands for **you alone**. When an admin of the
host's project gives another member `exec.device` or `terminal.device`, that
member's commands and terminal tabs still run only in the folders you opened to
others:

```bash
neuralis device grant ~/shared --host https://company.example.com --others exec   # others may run commands here
neuralis device grant ~/shared --host https://company.example.com --others none   # yours alone again
```

Elsewhere such a command is refused as `others_denied`, and nothing is recorded
as a request. Reading and writing files in a folder are decided by the source
you attach there and its path policies — which only you can attach, since
attaching a source on a device is the owner's act.

<Callout type="warn" title="What this setting protects against">
The host tells the device whether a command is for its owner or for someone
else, so the "others" setting guards against members of a host you trust. Against
a host you do not trust, the hard limit is the folder list itself: give that host no
folder it should not reach.
</Callout>

## Requests and grants [#requests-and-grants]

When an agent asks for a folder you have not granted, the device records the
request — the folder, the host that asked, and the agent's reason — and refuses
the command. You can ask for one yourself too: when you attach a folder of your
own device in **Files → Sources** and pick one it does not allow yet, **Ask on
that device** records the same kind of request (its reason says it is for a
source). You answer on the machine (`neuralis device grant`, or **Answer…** on
the desktop app's **This computer** page), and a grant clears the request. The queue keeps the most
recent requests; asking for ever-new folders cannot grow it without bound.

In the app, the Admin widget's **Devices** tab shows a device's pending
requests: your own device's to you, another member's through the roster that
shows it — the project's (the device carries a source you can see there) or
the platform's (`platform.users`). A row shows the folders the command asked
for and the agent's reason. Reading is all the app does; granting stays
on the machine.

## Leaving a host [#leaving-a-host]

```bash
neuralis device unpair --host https://company.example.com
```

The computer forgets that host: its link secret, its pairing and its folders.
A running device closes that link at once, and the terminals and background
commands that host opened on this computer end with it; every other host stays paired. The
host still lists the device until it is revoked there — in the Admin widget's
**Devices** tab.

In the app, you rename your own device (your agent can too); pairing and
revoking are a person's acts, refused to an agent. Another user's device is
revoked only from the browser, by a `platform.users` holder, who first sees how
many open terminals and background runs it would end. A revoked device stays on
record until a person removes it for good (**Remove device** in the **Devices** tab);
its audit history stays.

## Folders on a device [#folders-on-a-device]

A folder on a device is a source like a folder on the server, reached through
the device's broker: listing, reading, writing, scans and live change events,
all clamped twice — by the source's own path policies in the app and by the
device's allowlist on the machine. A path is resolved to its real location
before it is checked, so a symbolic link cannot lead out of an allowed folder,
and a toolchain root (`--exec`) can run but is never readable. While the device
is offline, the folder's indexed text stays searchable. Git on a folder on a
device is not available yet.

Such a folder belongs to you: it defaults to **user scope** and cannot be
scoped to an agent. In user scope it serves only you; project owners and admins
do not see or read it either. Project scope is an explicit opt-in, because
members and viewers may read an attached source by default.

<Callout type="warn" title="Whole-home access is trusted-owner mode">
If both the folder and the device's allowlist grant your entire home directory
read/write, commands can also reach credentials and control files inside it.
Only the device's own folder and toolchain are carved out of such a grant; any
other sensitive child directory is not: keep grants narrow, and run a device
that serves other people's commands under a separate OS account.
</Callout>

## The sandbox [#the-sandbox]

Every command a device runs goes through its operating system's own sandbox —
Landlock on Linux, Seatbelt on macOS, Microsoft's process containers on
Windows 11 — proven on the machine before the first command runs. A device whose
sandbox does not prove itself serves only its owner, after an explicit
`neuralis device grant --unconfined`; `--unconfined --revoke` returns it to the
sandbox. On Windows, commands and background runs are PowerShell (pwsh 7 when
installed, else Windows PowerShell 5.1) and the terminal is `cmd`. A bare `node`
in a command is your own Node.js when the machine has one; only when it has none
does it resolve to the Node.js bundled with Neuralis — nothing is installed. If
your own Node.js lives where the sandbox cannot run it (an nvm or fnm install in
your profile), allow its folder: `neuralis device grant <node folder> --exec`. A command
exits with a native program's non-zero code, otherwise 1 when its last command
wrote an error, and Node runs there with `--preserve-symlinks
--preserve-symlinks-main` added to `NODE_OPTIONS`. A server a command starts inside the Windows
sandbox cannot be reached from the host or from a browser. WSL on the
same PC is its own device: run `neuralis device pair` inside WSL; it reaches a
desktop app on the same PC only with WSL's mirrored networking. Each device
serves the folders its owner allowed, and beside them only the read-only
system folders (and `/tmp` on Linux) — but a WSL folder under `/mnt/c`, or
a Windows folder under `\\wsl.localhost`, is the other side's disk, so allow
those with care. Because the device dials out, Docker Desktop needs nothing
extra. The [security model](https://docs.neuralisapp.com/enterprise/security.md) has the guarantees behind
this, and [platforms](https://docs.neuralisapp.com/getting-started/platforms.md) how far each OS sandbox is
proven.
