ecmaOS: A web-native operating system and framework for web technologies
npm install @ecmaos/kernel
> Made with ❤️ by Jay Mathis
>
>  
ecmaOS is a browser-based operating system kernel and suite of applications written primarily in TypeScript, AssemblyScript, and C++. It's the successor of web3os.
The goal is to create a kernel and supporting apps that tie together modern web technologies and utilities to form an "operating system" that can run on modern browsers, not just to create a "desktop experience". It offers the ability to run a wide variety of apps on top of an already (mostly) sandboxed foundation, offering some measure of security by default as well as rich developer tooling. Its main use case is to provide a consistent environment for running web apps, but it has features that allow for more powerful custom scenarios, such as a platform for custom applications, games, and more.
This is NOT intended to be a "Linux kernel in Javascript" - while it takes its heaviest inspiration from Linux, it is more experimental and follows different design principles and architecture, and also doesn't need to cover nearly the same scope.
---
> "The computer can be used as a tool to liberate and protect people, rather than to control them."
> — Hal Finney
- TypeScript, WebAssembly, AssemblyScript, Rust, C++
- Filesystem supporting multiple backends powered by zenfs
- Terminal interface powered by xterm.js
- Streams for handling input and output, allowing redirection and piping
- Device framework with a common interface for working with hardware: WebBluetooth, WebSerial, WebHID, WebUSB, etc.
- Some devices have a builtin CLI, so you can run them like normal commands: # /dev/bluetooth
- WebAssembly binaries are the native executable format; # ./hello.wasm --world
- Many common files can be viewed directly: # ./image.jpg, # ./doc.pdf
- Install any client-side npm package; # install axios
- Event manager for dispatching and subscribing to events
- Process manager for running applications and daemons
- Interval manager for scheduling recurring operations with support for cron expressions via the cron command
- Memory manager for managing pseudo-memory: Collections, Config, Heap, and Stack
- Storage manager for managing Storage API capabilities: IndexedDB, localStorage, etc.
- User manager for managing users and authentication (all client-side, so limited real security but useful for organizational purposes)
- Internationalization framework for translating text powered by i18next
- Window manager powered by WinBox
- Metal: An API server for allowing connections to physical systems from ecmaOS using Hono
- SWAPI: An API server running completely inside a service worker using Hono
> /apps
- These are full applications that are developed specifically to work with ecmaOS
- Refer to the full list of official published apps on npm
- See the APPS.md file for a list of community apps; submit a PR to add your app!
- An app is an npm package, in which the bin file has a shebang line of #!ecmaos:bin:app:myappname
- Its default export (or exported main function) will be called with the ProcessEntryParams object
- They can be installed from the terminal using the install command, e.g. # install @ecmaos-apps/code
- Run the installed app (bins are linked to /usr/bin): # code /root/hello.js
- During development, it can be useful to run a Verdaccio server to test local packages
- To publish to Verdaccio, run # npm publish --registry http://localhost:4873 in your app's development environment
- Then to install from your local registry, run (inside ecmaOS) # install @myscope/mypackage --registry http://localhost:4873
> /core/kernel/src/tree/wasm.ts
- The native binary format for ecmaOS is WebAssembly
- The kernel supports both WASI Preview 1 and WASI Preview 2 (WIP)
- You can run WASM binaries directly:
- /root/bin/hello.wasm --help
- The .wasm extension is optional
- Compiling can be as simple as:
- $ rustc --target wasm32-wasip1 -o hello.wasm hello.rs
- $ emcc -o hello.wasm hello.c -sSTANDALONE_WASM
- You can also load WASM+JS harnesses manually
> /core/kernel/src/tree/lib/commands
- Commands are built-in shell commands that are provided by the kernel, e.g. download, install, load, etc. Many or all of these will be migrated to the @ecmaos/coreutils package in the future.
- Coreutils are similar to Commands, but are provided by the @ecmaos/coreutils package, e.g. cat, cd, chmod, cp, echo, git, ls, mkdir, mv, pwd, rm, rmdir, stat, touch, etc.
> /devices
- Refer to the full list of official devices on npm
- See the DEVICES.md file for a list of community devices; submit a PR to add your device!
- Devices get loaded on boot, e.g. /dev/bluetooth, /dev/random, /dev/battery, etc.
- A device can support being "run" by a user, e.g. # /dev/battery status
- Devices may also be directly read/written using fs methods, and will behave accordingly (or have no effect if not supported)
- An individual device module can provide multiple device drivers, e.g. /dev/usb provides /dev/usb-mydevice-0001-0002
> /core/utils/src/commands/mount.ts
ecmaOS supports multiple filesystem backends powered by zenfs, allowing you to mount various storage types into the virtual filesystem.
#### Supported Filesystem Types
- memory: In-memory filesystem (temporary, lost on page reload)
- indexeddb: IndexedDB-backed persistent filesystem
- webstorage: WebStorage-backed filesystem (localStorage or sessionStorage)
- webaccess: File System Access API filesystem (requires user interaction)
- singlebuffer: Filesystem backed by a single buffer
- fetch: Remote filesystem via HTTP fetch
- xml: DOM XML filesystem (WIP)
- zip: Read-only filesystem from a zip archive (file or URL)
- iso: Read-only filesystem from an ISO image (file or URL)
- dropbox: Dropbox filesystem (WIP)
- s3: S3 filesystem (WIP)
- googledrive: Google Drive filesystem (WIP)
#### Basic Usage
``shMount a memory filesystem
mount -t memory /mnt/tmp
#### /etc/fstab
The kernel automatically processes
during boot to mount filesystems. The fstab format is space or tab-separated:`plaintext
source target type [options]
`Format:
-
: Device/URL/database name (use none for filesystems that don't require a source)
- target: Mount point (absolute path)
- type: Filesystem type
- options: Optional comma-separated key=value pairsExample /etc/fstab:
`plaintext
ecmaOS fstab - Filesystem mount table
Format: source target type [options]
Memory filesystem for temporary data
none /mnt/tmp memoryIndexedDB filesystem for persistent storage
mydb /mnt/db indexeddbWebStorage filesystem using localStorage
none /mnt/storage webstorage storage=localStorageFetch filesystem from a remote API
index.json /mnt/api fetch baseUrl=http://localhost:30808
`$3
- Generators are used to scaffold new apps, devices, modules, etc.
- They are located in the
directory of the repository
- They are used by the turbo gen command, e.g. turbo gen app, turbo gen device, turbo gen module, etc.
$3
- Built-in translations are in the /core/kernel/locales directory and compiled into the kernel at build time
- Translations can be defined and loaded from the filesystem at runtime
- Override or add translations in
/usr/share/locales/{lang}/{namespace}.json
- e.g.
- System locale can be set from the file
- User locale can be set from the LANG environment variable
- kernel.i18n.t is the primary translation function for the kernel
- kernel.i18n.ns provides access to translation functions for specific namespaces
- e.g. kernel.i18n.ns.common('Hello')$3
- The kernel ties together the various components of the system into a cohesive whole
- Authentication (Passwords, Passkeys, Credentials)
- Components (Web Components/Custom Elements)
- Coreutils (Built-in commands)
- Devices (Web Hardware APIs)
- DOM (DOM Utilities and Interfaces)
- Events (CustomEvents)
- Filesystem (ZenFS)
- Internationalization (i18next)
- Interval Manager (setInterval and cron scheduling)
- Log Manager (tslog)
- Memory Manager (Abstractions)
- Process Manager
- Protocol Handlers (web+ecmaos://...)
- Service Worker Manager
- Shell
- Sockets (WebSocket, WebTransport)
- Storage (IndexedDB, localStorage, sessionStorage, etc.)
- Telemetry (OpenTelemetry)
- Terminal (xterm.js)
- User Manager
- WASM Loader (WASI Preview 1 mostly complete; WASI Preview 2 WIP)
- Web Workers
- Window Manager (WinBox)
$3
- Metal is an API server for allowing connections to physical systems from ecmaOS using Hono
- Authenticated and encrypted connections with JWK/JWE/JOSE
$3
> /modules
- Refer to the full list of official modules on npm
- See the MODULES.md file for a list of community modules; submit a PR to add your module!
- Modules are dynamically loaded into the kernel at boot and can be enabled or disabled
- They are specified during build via the
environment variable
- e.g. ECMAOS_KERNEL_MODULES=@ecmaos-modules/boilerplate@0.1.0,@your/package@1.2.3
- Versions must be pinned and are mandatory - you cannot use NPM version specifiers
- They can provide additional functionality, devices, commands, etc.
- They offer a common interface for interacting with the kernel
- Generally they should be written in AssemblyScript, but this isn't required$3
- Packages are NPM packages that are installed into the ecmaOS environment
- They can be installed from the terminal using the
command, e.g. # install @ecmaos-apps/ai
- Client-side packages should work well
- Some basic Node emulation is in place, but don't expect anything to work at this point
- NPM version specifiers are supported, e.g.:
-
-
-
- JSR may be used with the NPM compatibility layer:
- $3
- Current options:
, matrix, toasters
- This whole system will be revamped in the future
- Screensavers are currently built into the kernel, but will be migrated to external apps
- You can start the screensaver with the command
- You can set the default screensaver with the screensaver --set command
- The screensaver timeout can be set with a screensaver-timeout localStorage key with the value in milliseconds (default: 60000)$3
- The shell manages the environment, filesystem context, execution, and terminal interface
- System-wide shell configuration is stored in
/etc/shell.toml
- User-specific shell configuration is stored in
- See tutorials/shell-customization.md for more information$3
- A socket manager is available for creating and managing WebSocket and WebTransport connections
- It can be accessed via the
property or the sockets command$3
- The SWAPI is an API server running completely inside a service worker using Hono
- It allows for various operations including the
fs route to fetch files via URL
- e.g., # fetch /swapi/fs/home/user/hello.txt
- e.g., $3
- OpenTelemetry is used for collecting and analyzing telemetry data from the kernel and applications
- It is only active if the ECMAOS_OPENTELEMETRY_ENDPOINT environment variable is set when building the kernel
- There is a simple test server included in the
directory that can be used to test the telemetry system: python3 utils/opentelemetry/otlp-server.py$3
> /utils
- Utilities and configuration used during development
Important Files and Directories
-
: Built-in commands
- /boot/init: A script that runs on boot
- /dev/: All devices are here
- /etc/crontab: System-wide crontab file (loaded on boot)
- /etc/packages: A list of installed packages to load on boot
- /etc/shell.toml: System-wide shell configuration
- /home/: Contains user home directories
- ~/.config/crontab: User-specific crontab file (loaded on login)
- ~/.config/shell: User-specific shell configuration
- /proc/: Contains various dynamic system information
- /root/: The home directory for the root user
- /usr/bin/: Executable packages get linked here
- /usr/lib/: All installed packages are here
- /var/log/kernel.log: The kernel logCommand Examples
`sh
ai "Despite all my rage" # use env OPENAI_API_KEY=
cat /var/log/kernel.lo
cd /tmp
echo "Hello, world!" > hello.txt
chmod 700 hello.txt
chown user hello.txt
clear
cp /tmp/hello.txt /tmp/hi.txt
cron add " *" "echo hello" # add a cron job
cron reload # reload crontabs from files
cron list # list all cron jobs
download hello.txt
edit hello.txt
env hello=world ; env
fetch https://ipecho.net/plain > /tmp/myip.txt
fetch -o /tmp/initfs.tar.gz /initfs.tar.gz
fetch /initfs.tar.gz | head | xxd
fetch /xkcd-os.sixel # xterm.js includes sixel support
fetch /swapi/fs/home/user/hello.txt # fetch a file from the filesystem via SWAPI
fetch /swapi/fake/person/fullName # fetch a random person from the SWAPI
install jquery
install @ecmaos-apps/boilerplate
ls /dev
mkdir /tmp/zip ; cd /tmp/zip
upload
mount -t zip myuploaded.zip /mnt/zip
cd .. ; pwd
unzip zip/myuploaded.zip
mv zip/myuploaded.zip /tmp/backup.zip
passwd old new
play /root/test.mp3
ps
rm /tmp/backup.zip
screensaver
snake
stat /tmp/hello.txt
touch /tmp/test.bin
umount /mnt/zip
user add user
su user
video /root/video.mp4
zip /root/tmp.zip /tmp
Device Examples
sh
/dev/audio test
/dev/battery status
/dev/bluetooth scan
/dev/gamepad list
/dev/geo position
/dev/gpu test
/dev/hid list
/dev/midi list
/dev/presentation start https://wikipedia.org
/dev/sensors list
/dev/serial devices
/dev/usb list
/dev/webgpu test
echo "Goodbye" > /dev/null
echo "This will error" > /dev/full
head -c 32 /dev/random > /tmp/random.txt
head -c 32 /dev/zero > /dev/null
`Code Execution Example
sh
echo "window.alert('Hello, world!')" > /root/hello.js
load /root/hello.js
`Scripting
txt
#!ecmaos:bin:script
echo "Hello, world!"
install jquery
`Startup
-
is a script that runs on boot inside the init process (PID 0)
- /etc/crontab is loaded on boot and contains system-wide scheduled tasks
- ~/.config/crontab is loaded on user login and contains user-specific scheduled tasks
- /etc/packages is a list of already installed packages to load on boot; one per line
- The env var ECMAOS_KERNEL_MODULES is a list of modules to load on boot; CSV with pinned versions
- The env var ECMAOS_RECOMMENDED_APPS is a list of apps to suggest to new usersApp Development
The apps directory in the repository contains some examples of how to develop apps, but there are many approaches you could take.
-
@ecmaos-apps/boilerplate: A minimal boilerplate app for reference
- @ecmaos-apps/code: A simple code editor app using Monaco; serves as a good reference for more complex appsBasically, your app's bin file has a
main (or unnamed default) function export that is passed the kernel reference and can use it to interact with the system as needed. A shebang line of #!ecmaos:bin:app:myappname is required at the top of the bin file to identify it as an app.App/Kernel Interface Example
> See the docs for more information
`ts
#!ecmaos:bin:app:example
// shebang format: ecmaos:exectype:execnamespace:execname
export default async function main(params: ProcessEntryParams) {
const { args, kernel, terminal } = params
kernel.log.info('Hello, world!')
kernel.log.debug(args)
terminal.writeln('Hello, world!')
await kernel.filesystem.fs.writeFile('/tmp/hello.txt', 'Hello, world!')
const win = kernel.windows.create({ title: 'Example', width: 800, height: 600 })
const container = document.createElement('div')
container.innerHTML = 'Hello, world!
'
win.mount(container)
}
`Early Days
ecmaOS is currently in active development. It is not considered stable and the structure and API are very likely to change in unexpected and possibly unannounced ways until version 1.0.0. Use cautiously and at your own risk.
Things to keep in mind:
- If things go wrong or break, clear your browser cache and site data for ecmaOS
- The tests need to be updated and expanded
- The kernel is designed to be run in an environment with a DOM (i.e. a browser)
- Many features are only available on Chromium-based browsers, and many more behind feature flags
- There will be a lot of technical challenges to overcome, and many things will first be implemented in a non-optimal way
- Command interfaces won't match what you might be used to from a traditional Linux environment; not all commands and options are supported. Over time, Linuxish commands will be fleshed out and made to behave in a more familiar way.
Development
Until v1.0.0, active development will occur on the
branch. Once a v1.0.0 release is made, development will shift to a dev branch, and main will be reserved for stable releases.Turborepo is used to manage the monorepo, and pnpm is used for package management.
PNPM Workspaces:
- apps
- core
- devices
- modules
- utils
A good place to start is viewing the
scripts property of package.json in the root of the repository.`bash
Clone
git clone https://github.com/ecmaos/ecmaos.gitInstall dependencies
cd ecmaos && pnpm installRun the dev server
pnpm run dev:kernelRun the docs server (optional)
pnpm run dev:docsBuild
pnpm run buildRun tests
pnpm run test
pnpm run test:watch
pnpm run test:coverage
pnpm run test:bench
pnpm run test:uiGenerate modules
turbo gen app # generate a new app template
turbo gen device # generate a new device template
turbo gen module # generate a new module template
``Also see turbo.json and CONTRIBUTING.md for more information.
See SECURITY.md for more information.
If you find a serious security vulnerability, please submit a new Draft Security Advisory or contact the project maintainer directly at code@mathis.network.