# Chapter 4 — Shell, PATH, and scripts

**Prerequisites:** [Running seeder and booter](03-running-seeder-and-booter.md). **Time to read:** about six minutes.

---

## On this page

- [Line shell and `/bin`](#line-shell-and-bin)
- [How a command runs (conceptually)](#how-a-command-runs-conceptually)
- [User scripts and PATH](#user-scripts-and-path)
- [What is different from Node on the host](#what-is-different-from-node-on-the-host)
- [Example commands (safe to try)](#example-commands-safe-to-try)
- [`agent` and `chat`](#agent-and-chat)
- [Builtins, `/bin`, and `/proc`](#builtins-bin-and-proc)

---

## 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](../docs/reference/shell-completion-and-repl-editor.md)). 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](../handbook/09-posix-utilities-shell-and-vfs.md).

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

```mermaid
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](../developer-guide/04-user-scripts-and-path.md) and [Developer guide — The context object](../developer-guide/02-the-context-object.md).

---

## 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](../developer-guide/01-two-runtimes-host-vs-image.md). For guest-safe module choices, see [Node → Bare module map](../developer-guide/node-to-bare-modules.md).

---

## Example commands (safe to try)

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

```sh
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](../handbook/03-protocol-and-disk.md) for P2P context.

Maintainer sources: [`packages/bare-os-coreutils/src/agent.js`](../packages/bare-os-coreutils/src/agent.js), [`packages/bare-os-coreutils/lib/agent-*.js`](../packages/bare-os-coreutils/lib/) (agent preamble), [`packages/bare-os-coreutils/src/chat.js`](../packages/bare-os-coreutils/src/chat.js), [`packages/bare-os-coreutils/lib/chat-tui.js`](../packages/bare-os-coreutils/lib/chat-tui.js). HTTP policy (for **`agent`**): [HTTP: curl and wget](../docs/reference/http-curl-and-wget.md).

---

## 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](../docs/reference/kernel-extensions.md) 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](03-running-seeder-and-booter.md)_ · _Next: [Chapter 5 — Home, identity, and vault](05-home-identity-and-vault.md)_