106 lines
7.1 KiB
Markdown
106 lines
7.1 KiB
Markdown
# 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)_
|