N-Bash — Remote Bash for NeuronDB

Interactive SNL terminal and remote bash executor for NeuronDB.

Install

npm install -g neurondb

(The package name is neurondb; it installs the nbash, neuron and neuron-bash commands.)

Usage

nbash
# or
neuron-bash

You'll be prompted for:

• Node URL — NeuronDB server (e.g., https://api.neuron-db.com)
• Instance — NeuronDB instance (default: system)
• Username / Password — Your NeuronDB credentials
• Session name — Name for this bash session (default: hostname)

Features

Interactive SNL Terminal

Type any SNL command and it executes on the server:

nbash> GET() ON(main.users.*) GO()
nbash> SET() VALUE({"hello":"world"}) ON(main.test.key1) GO()

Remote Bash Execution

From NeuronDB Studio or another terminal, run commands on the machine where nbash is connected:

BASH("ls -la") GO(result)
BASH("echo hello", "my-laptop") GO(result)
CATALOG(Bash) GO()

Results are written to __nbash_results.{request_id} and can be retrieved with:

GET() ON(system.main.__nbash_results.{request_id}) GO(data)

Shared runner (--shared)

By default an agent is personal: only the user it logged in as can dispatch to it. --shared publishes it as an instance-wide runner instead — every authenticated user of that instance can send commands to it, and so can a scheduled workflow, which has no user of its own to borrow a session from.

nbash --shared                 # read-only runner for the whole instance
nbash --shared --allow-write   # …and it may change state on this machine

Two things make this safe to offer:

• Publishing needs admin. A shared session registers under __$session_shared, which a plain user cannot write. Whoever can publish a runner is the only one who decides it exists.
• Read-only by default. The policy travels in the session record, so no individual user can loosen it — --allow-write at launch is the explicit act of letting the whole instance change state on that machine.

Requires a NeuronDB server with shared-runner support (core 4.3.269+). Run one agent per session name: two agents polling the same shared queue will race for the same commands.

Sandbox Security

All commands execute in ~/neuron-home/{instance}/ with:

• Restricted PATH
• 30s timeout
• 1MB output buffer
• Blocked dangerous commands (sudo, rm /, etc.)
• Path traversal prevention

Requirements

• Node.js >= 18.0.0
• A running NeuronDB server

License

MIT