Chapter 4 — Shell, PATH, and scripts

Prerequisites: Running seeder and booter. Time to read: about six minutes.

Line shell and `/bin`

Inside the booted image you interact through a line-oriented shell (Fish-style line editor with tab completion and history unless BARE_OS_FISH=0 — see Shell completion and REPL editor). It supports pipelines, redirects, wildcards (*, ?, […]) on unquoted words against the VFS (quotes keep characters literal: echo '*' vs echo *), and a broad set of utilities under /bin, including text tools such as sed and awk. Use set -f / set +f to turn globbing off or on for the session (BARE_OS_SHELL_NOGLOB).

The shell and utilities are part of the guest runtime built by the booter. They are not the same process as your host’s system shell; they execute against the virtual file system that merges the system drive, personal drive, and synthetic mounts such as /proc.

For POSIX coverage and deliberate gaps, see Handbook — Chapter 9.

flowchart LR
  line[User types line]
  parse[Parse lists pipes redirects]
  expand[Expand words globs]
  runStage[Builtin or /bin]
  vfs[VFS read write]
  line --> parse --> expand --> runStage --> vfs

Pipeline capture (conceptual): stages connected by | pass simulated stdout between utilities (bounded bytes/lines); this is not a host OS pipe.

flowchart LR
  cmdA["First command"] --> cap[Captured stdout]
  cap --> cmdB["Next in pipeline"]
  cmdB --> out[Console or file redirect]

How a command runs (conceptually)

When you type a command name, the runtime resolves it against PATH. Built-in and /bin tools are implemented as guest JavaScript evaluated in a controlled way (no arbitrary Node import graph for drive-resident scripts). The booter supplies a ctx object that exposes the VFS, environment, subprocess helpers, and many optional bridges; in-image user scripts use the run(ctx, argv) convention.

You do not need the full ctx reference to use the system day to day. When you start writing or packaging scripts, read Developer guide — User scripts and PATH and Developer guide — The context object.

User scripts and PATH

Scripts on your personal or system drive can be executed when they are discoverable on PATH or invoked with a ./ path, subject to shebang and permission rules described in the developer guide. The stock kernel’s readline loop hands lines to the shell, which may invoke /bin tools or launch ***.js** handlers.

If a command is not found, verify PATH, whether the file is executable in the VFS sense, and whether you are in guest versus unlocked identity (some locations are only writable or meaningful after login).

What is different from Node on the host

Pear and Node on your laptop run ESM packages with normal import. Drive-resident scripts inside Bare OS follow the in-image execution model: they are not a second copy of Node with free module resolution. That distinction matters when you port tools from npm or expect node: built-ins to exist unchanged.

For a careful comparison of the two runtimes, read Developer guide — Two runtimes: host vs in-image. For guest-safe module choices, see Node → Bare module map.

Example commands (safe to try)

After the shell prompt appears, these exercises help build intuition without touching identity material:

uname -a
echo $HOME $USER
ls -la /bin | head
man ls | head -n 20

Pipelines and redirects behave like a small Unix (ls | wc -c, echo hello > /tmp/x), but paths such as /tmp map through the VFS—not every corner case matches Linux. When a command fails, read the stderr line first; many utilities print usage: hints aligned with man.

`agent` and `chat`

These are different commands:

agent — OpenAI-compatible HTTPS assistant with a ReAct-style tool loop (streaming on a TTY). Credentials and provider settings live under **~/.agent/** on the personal drive (**~/.agent/config.json** — not host environment variables). Use agent --setup on a TTY to create or adjust that file. Outbound HTTPS uses the same ctx.httpFetch path as delegated curl / wget (HTTP allow/deny lists, optional audit). The web_fetch tool fetches live http(s) URLs for the model; operators using BARE_OS_HTTP_ALLOWLIST must include both the API host (for example api.groq.com) and any hosts you expect web_fetch to reach. Full detail: man agent.
chat — Swarm / Protomux chat: full-screen TUI on a TTY when the booter exposes swarm chat, or scriptable subcommands (send, history, who, join, …). It is not the same program as agent. See man chat and Handbook — Chapter 3 for P2P context.

Maintainer sources: packages/bare-os-coreutils/src/agent.js, packages/bare-os-coreutils/lib/agent-*.js (agent preamble), packages/bare-os-coreutils/src/chat.js, packages/bare-os-coreutils/lib/chat-tui.js. HTTP policy (for agent): HTTP: curl and wget.

Builtins, `/bin`, and `/proc`

The shell implements builtins (cd, export, control flow, …) in packages/bare-os-booter/lib/shell.js. Everything else normally resolves to /bin/<name> via PATH. Synthetic trees such as /proc/bare_os_features expose JSON or text summaries of capabilities and runtime state; they are documented in the kernel extensions reference and handbook chapters on the booter. If a name does not resolve, verify you are not shadowing a shell builtin and that PATH includes /bin (try **command -v <name>** when the shell supports it, or which <name> if installed).

Previous: Chapter 3 · Next: Chapter 5 — Home, identity, and vault

7.1 KiB Raw Blame History Unescape Escape

Chapter 4 — Shell, PATH, and scripts

On this page

Line shell and /bin