Devices
Pair a computer with one or more Neuralis hosts, decide which folders each host may reach and whether other members may run commands there, and leave a host again — the owner decides, on the machine.
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).
Pair this computer
Run on the machine itself:
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). 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.
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 backThe 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).
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
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.
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 backWith 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
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:
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 againElsewhere 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.
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.
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
neuralis device unpair --host https://company.example.comThe 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
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.
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.
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 has the guarantees behind
this, and platforms how far each OS sandbox is
proven.
Join a team
Join a team's Neuralis from an invite link — in the browser, in the desktop app or from the CLI — and, if you want, let that host use your own computer as a device.
Neuralis CLI
Sign in from your own machine, call package routes as yourself, install packages into your host, pair this computer as a device, and start Claude Code or Codex with your Neuralis skills, tools and context.