Hello World

What you’ll build: A running fishbowl shell environment that you can type commands into.

Prerequisites: None. This is the starting point.

---

Install

npm install @fishnet/core @fishnet/runtime

The package is isomorphic — the same install works for Node.js and browser (via a bundler like Vite or esbuild).

Boot a shell

Node.js

import { Unix } from '@fishnet/core'
import { stdSystem } from '@fishnet/core/presets'
import { nodeRuntime } from '@fishnet/runtime/platform/node'

const image = Unix().use(stdSystem()).build()
const runtime = nodeRuntime()
const instance = await image.boot(runtime)

// instance.shell() returns a promise that resolves when the shell exits
await instance.shell()

Browser

import { Unix } from '@fishnet/core'
import { stdSystem } from '@fishnet/core/presets'
import { browserRuntime } from '@fishnet/runtime/platform/browser'

const image = Unix().use(stdSystem()).build()
const runtime = browserRuntime()
const instance = await image.boot(runtime)

// Same API — swap nodeRuntime() for browserRuntime() above
await instance.shell()

Try it live

What just happened

You have a running Unix environment. stdSystem() loaded the standard bins and shell. Each call to .boot() produces an independent, isolated instance.

The stdSystem() preset includes:

• All GNU coreutils (ls, cat, echo, grep, …)
• Shell builtins (cd, export, set, source, …)
• The package manager (pkg update, pkg install, …)
• An HTTP fileserver (/net/http)
• Process and system tools (ps, kill, dmesg, …)

Next steps

• Filesystem guide → — Mount additional fileservers and create overlay layers
• Custom Package guide → — Add your own bins to the system

Further reading

• Unix() builder → — API reference for the builder entry point
• Extension interface → — How extensions compose into an image
• Bootstrap → — What happens during .boot()