Getting started

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 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).

Who decides what

DecisionWho makes itWhere
Pair the computer with a hostthe person who will own it (device.own)on the machine: neuralis device pair --host <url>
Which folders a host may read or writethe device's owneron the machine: neuralis device grant <dir> [--write] [--host <url>]
Whether other members may run commands in a folderthe device's owneron the machine: neuralis device grant <dir> --others exec
Which members may use another member's device at allthe project's admins, through rolesthe app: exec.device / terminal.device
Run without the OS sandboxthe device's owner, explicitlyon the machine: neuralis device grant --unconfined
The device's own sign-in and keysnobody — no grant reaches themfixed: 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 homenobody through a grant — your own commands keep the project folders and run installed packagesfixed: 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 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

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 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.

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.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

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.

On this page