Capabilities

Shell & Processes

fishbowl gives you a real shell. You can write pipelines, redirect I/O, run subshells, and use control flow. Processes are independent: each has its own environment, working directory, and view of the filesystem. You can run any command available on PATH, or add your own by writing a bin function.

The same shell code runs in Node.js and the browser.

Filesystem

There is no disk. The filesystem is virtual — composed from fileservers you mount when you boot. The default is an in-memory tree. You can add more: overlay a writable layer on top of a read-only base, combine multiple servers at a single path, or mount any custom object that implements the fileserver protocol. Data written during a session lives only in memory unless you mount a fileserver backed by persistent storage.

Each process has a private view of the filesystem. Changes to one process’s view don’t affect other processes. Isolation is automatic.

Packages & Registry

Packages are how you distribute and install capabilities. A JS package adds bins, fileservers, or services to a running system. A WASM package ships a compiled binary that runs inside the same filesystem as your JS code.

Installing a package works like you’d expect: pkg install, pkg update, pkg search. Semver resolution, HTTP registry, the same UX as npm or apt — without touching the host machine.

Agent Harness

In development

The agent harness is under active development. What’s described here is the planned API — the foundation is being built now.

Instead of exposing a list of tool call schemas, you give the agent a Unix environment. Tool calls map to filesystem operations: read a file to observe state, write a file to trigger an action. The harness will provide typed output streams, task state as files, and a clean separation between agent I/O and user I/O.

Today, the Containers → and Custom Package → guides cover the foundation the harness will build on.

WASI / WASM

You can run programs written in Rust or C/C++ inside a fishbowl environment. They see the same virtual filesystem as your JS code, can read stdin and write stdout, and are isolated from the host.

Rust compiles to WASI and runs directly inside the fishbowl filesystem. C/C++ compiles through Emscripten and the filesystem is bridged in and out around execution. Both support blocking I/O — a Rust program that reads from stdin works the same in fishbowl as it does natively.

Containers

You can boot multiple independent environments from the same image. Each container has a private filesystem, its own process tree, and its own init system. They share nothing by default. The host can observe any container; containers cannot see each other.

The builder API — Unix().use(ext).build() — produces an immutable image you can boot as many times as you want.