"The computer can be used as a tool to liberate and protect people, rather than to control them." -Hal Finney

A decentralized web-based operating system for the next web, empowering users and developers to:

Easily install many npm browser packages
Run Node.js code using RunKit
Customize the OS to suit your individual needs
Write scripts to perform particular tasks
Write full applications that can create windows and interface with the kernel
Interact with crypto wallets and smart contracts
Utilize a number of P2P protocols within the browser

Documentation: https://docs.web3os.sh

The project is still very young, and more documentation and organization is Coming Soon™.

Features
Disclaimer
Help Wanted
User Quickstart
Developer Quickstart
Autostart
Globals
Shortcuts
Scripting
Web3os Package Manager
Official Apps
Three (OS Assistant)
Kernel Interface
App Structure
Metal (@web3os-core/metal)
WebUSB
Web Bluetooth
TODO
Can it do thing?
Further Documentation

Features

Expand Features

Runs completely in the browser (Chromium-based browsers are ideal)
Web-based terminal with xterm.js
3pm: The web3os package manager
Modules may also be imported with SystemJS
Installable as a Progressive Web App
Optional desktop environment
Optional backend environment runs in Docker container
Provides interfaces for many standard and experimental browser APIs
WebSocket support
WebUSB support
WebHID support
Web Bluetooth support
Gamepad support
Web3 wallet integration with web3.js
Fully in-browser filesystem with BrowserFS
IPFS Integration with js-ipfs
- Built-in IPFS video search (WIP) and player; type flix
Sexy dialogs with sweetalert2
Slick windowing system with WinBox
Decentralized messaging support with Mailchain
Git integration with isomorphic-git
GunJS integration with GUN
Moralis integration with Moralis
P2P communication (chat, audio, video, screenshare, fileshare) with PeerJS
Torrent integration with WebTorrent
It runs Doom (and Wolfenstein 3D! and other DOS stuff!) with JS-DOS
WebAssembly executable support (WIP):
- Native
- [WIP] WASI
- [WIP] Emscripten
- [WIP] AssemblyScript
Decentralized:
- Open source to customize and host your own copy
- Included Fleek and Netlify configs for easy deployment
- Main site hosted by Fleek at https://web3os.sh
- Backup site hosted on IPFS at https://web3os-sh.ipns.dweb.link/
Developer-friendly:
- Easily scriptable and customizable
- Use an initfsUrl query param to load a ZIP file from a URL to populate your filesystem
- Use a mountableFileSystemConfig query param to specify how your filesystems should be mounted
- Install nearly any browser package from npm
- Programs are just HTML/CSS/JS/WebGL, or any language that compiles to WebAssembly

Disclaimer

Expand Disclaimer

This project is still considered to be in an alpha state. All apps run in the same context and can access every other app, as well as the entire virtual browserfs.

The code in this repository has not been audited. Do not rely on it to keep anything safe, and never paste commands you don't understand. Anywhere, ever.

Heavily scrutinize any application or script you install or run, as well as its authors.

Help Wanted

Expand Help Wanted

It's going to take people far smarter than me to make this project achieve its full potential.

Please consider digging into the code and see what you can come up with and submit a PR!

Not sure where to start? Check out the issues!

See CONTRIBUTING.md

User Quickstart

Expand User Quickstart

Visit https://web3os.sh
Use ls and cd to look around the filesystem
Type help for generic helpful information
Type files /bin to browse all available commands
Learn more about commands: help [command]
Edit a file: edit /tmp/test.txt
Launch the desktop: desktop
Run the screensaver: screensaver
Play DOOM: doom
Play Wolfenstein 3D: wolfenstein
Read this README: markdown /docs/README.md
Launch the file explorer: files /docs
Launch a browser: www https://instacalc.com
Connect to your wallet: account connect
Check native coin balance: account balance
Check token balance: account balance USDC
Switch to another network: account chain polygon, account chain bsc, account chain 0x2
Interact with a smart contract: contract --help
🎉 Fire the Confetti Gun: confetti
See the list of official apps

Developer Quickstart

Expand Developer Quickstart

git clone git@github.com:web3os-org/kernel.git
cd kernel
pnpm install # or npm install
pnpm start # or npm start

From here, simply connect to https://localhost:30443 and accept the certificate warning.

Alternatively, install src/assets/ssl/localhost.crt to your trusted certificate store.

We use SSL locally so that all browser APIs work as expected.

Autostart

Expand Autostart

To modify the commands the system executes on startup:

edit /config/autostart.sh
For example, add desktop to the end of the file
Insert any additional commands you want to run on startup

Globals

Expand Globals

These objects are available on the global object (globalThis/window):

Kernel: The global kernel
Terminal: The kernel's main terminal
System: The SystemJS library

Shortcuts

Expand Shortcuts

Shortcuts are managed via a JSON object at /config/shortcuts and accessed using the open command.

Current shortcut types: execute - url

Example:

{
  "scarytime": {
    "type": "execute",
    "target": "snackbar Confetti attack! ; confetti --scalar 12"
  },

  "instacalc": {
    "type": "execute",
    "target": "www --no-toolbar --title Instacalc https://instacalc.com"
  },
    
  "github": {
    "type": "url",
    "target": "https://github.com"
  }
}

To open a shortcut: open <key>, e.g. open github

Scripting

Expand Scripting

Web3os scripts (.sh) are a simple line-by-line execution, while Javascript (.js) offers far more power.

To run a web3os script: sh /path/to/script.sh

Or from an app: window.Kernel.executeScript('/path/to/script.sh')

To run a Javascript script: eval /path/to/script.js

Or from an app: window.Kernel.execute('eval /path/to/script.js')

See some sample scripts at: https://github.com/web3os-org/sample-scripts

Web3os Package Manager

Expand Web3os Package Manager

The 3pm command can be used to manage installed packages. Installing a package adds an entry to /config/packages and all packages in this file are loaded on startup.

Packages are generally ES Modules, located at a url that contains a package.json.

You can attempt to install any package from npm using a CDN such as unpkg (this is the default 3pm registry).

This means that during development, you can serve up your app locally, with Live Server for example, and 3pm install http://localhost:5500.

You may also just use the import command to directly import an ES module from a URL. Or bypass all of this and use your own technique!

Dependency management is another monster altogether, so that's still a WIP. This means your package should already be bundled when web3os loads it, or pull in your dependencies some other way.

Here are a few examples of npm libraries that can be successfully loaded in web3os:

lodash
- 3pm install lodash
- This doesn't add an executable, but _ is now available in the global scope.
jquery
- 3pm install jquery
- This doesn't add an executable, but $ is now available in the global scope.
moment
- 3pm install --umd moment
- const now = Kernel.modules.moment.run()
umbrellajs
- 3pm install umbrellajs --main umbrella.esm.js
- Now you can use it:
  - const u = Kernel.modules.umbrellajs.default
  - const body = u('body')

Official Apps

Expand Official Apps

@web3os-apps/doom
@web3os-apps/gun
@web3os-apps/minipaint
@web3os-apps/moralis
@web3os-apps/rubikscube
@web3os-apps/wolfenstein

See the full list

Note: some apps are currently either very basic implementations or just placeholders to be developed further

Three (OS Assistant)

Expand Three

(WIP)

Three is just a pet at this point, but eventually it will become a useful assistant.

Just type three at the terminal to get started!

Type three --help to see other commands you can use to control Three, and you can access all of the features on Kernel.modules.three, e.g.:

Kernel.modules.three.move('50%', '50%')
Kernel.modules.three.say('Hello world')
Kernel.modules.three.animate('heartBeat', 'infinite')
- Use any animate.css style

Three uses the speak command for speech synthesis. You may customize the voice parameters using the kernel memory as follows:

<3os># set three voice Google italiano
- Use speak --list-voices to see available voices
<3os># set three volume 2
<3os># set three pitch 1.5
<3os># set three rate 0.5

console.log(Kernel.modules.three) to inspect.

Kernel Interface

Expand Kernel Interface

This is a brief overview of how to use the kernel, please check https://docs.web3os.sh for updated documentation.

This (and everything else) is subject to change before version 1.0.

window.Kernel.modules = { name: app }

Contains all apps registered in the kernel
e.g., window.Kernel.modules.desktop.run()
e.g., window.Kernel.modules['@author/package'].version

window.Kernel.dialog ({ ...sweetalert2options }) = :Promise(sweetalert2result)

Convenience method to create a sweetalert2 dialog with appropriate defaults
e.g., window.Kernel.dialog({ title: 'Are you sure?', text: 'Scary stuff!', icon: 'warning' })

window.Kernel.fs = { ...BrowserFS }

This object holds the initialized BrowserFS instance
e.g., const doesExist = window.Kernel.fs.existsSync('/config/packages')

window.Kernel.set ('namespace', 'key', :any)

Sets a value in the kernel "memory" - persists in localStorage
e.g., window.Kernel.set('user', 'name', 'hosk')
e.g., window.Kernel.set('myapp', 'theme', { color: 'rebeccapurple' })

window.Kernel.get ('namespace', 'key') = :any

Gets a value from the kernel "memory" - loaded from localStorage
e.g., window.Kernel.get('user')
e.g., window.Kernel.get('user', 'name')
e.g., const { color } = window.Kernel.get('myapp', 'theme')

window.Kernel.windows.create (options) = { options, window }

Creates a new application window with WinBox options

App Structure

Expand App Structure

Developers should be able to create apps in any way they like, with as few requirements as possible. Remember, your app is simply running in a browser - you have access to everything that any other script or module does.

To make your module executable from the command line, you may export an async function named run, or your default export must be a function.

Your module or package.json may also contain a help property that contains your module's help text.

The best way to create applications for web3os is to create an npm package, using any bundler you'd like.

For example, to create an application with snowpack:

package.json:

{
  "name": "@yourorg/yourapp",
  "description": "A sample application",
  "version": "1.2.3",
  "license": "MIT",
  "main": "build/index.js",
  "module": "src/index.js",
  "scripts": {
    "start": "snowpack dev",
    "build": "snowpack build",
    "prepublishOnly": "npm run build"
  },
  "devDependencies": {
    "snowpack": "^3.8.8"
  }
}

index.js:

export const help = `
  This app enables developers to Do An App!

  Usage: @yourorg/yourapp [options]        Run yourapp with some options!
`

export async function run (terminal, context) {
// or: export default async function (terminal, context) {
  console.log(terminal) // the xterm.js terminal in which your app is running
  console.log(context) // the plain string of arguments passed to your app
  terminal.log('Thanks for checking out myapp!')
  terminal.log(context)

  // You may also access the web3os system terminal
  window.Terminal.log('This is output to the root globalThis.Terminal')
}

Apps can be written and bundled a number of different ways, for some ideas check out:

@web3os-apps

Metal (@web3os-core/metal)

Expand Metal

(WIP)

Metal is the web3os hardware link, allowing web3os access to certain hardware features and other capabilities of the host operating system.

It offers a multi-user environment while restricting access based on a user's authenticated wallet address, or other attributes such as NFT ownership, etc.

The metal command is the utility to connect to and interact with web3os metal servers.

View the metal repository

WebUSB

Expand WebUSB

Experimental WebUSB API features are limited in browser support at this time.

The usb command doesn't do much except pair and maintain a list of devices.

Usage:
    usb devices            List paired USB devices
    usb request <options>  Request USB device (blank for user choice)

  Options:
    --help                 Print this help message
    --name                 Specify a friendly name for the USB device
    --product              Product ID of the USB device
    --vendor               Vendor ID of the USB device
    --version              Print the version information

Access the array of devices within an app: Kernel.modules.usb.devices

WebHID

Expand WebHID

Experimental WebHID API features are limited in browser support at this time.

The hid command doesn't do much except pair and maintain a list of devices.

Usage:
    hid devices            List paired HID devices
    hid request <options>  Request HID device (blank for user choice)

  Options:
    --help                 Print this help message
    --product              Product ID of the HID device
    --vendor               Vendor ID of the HID device
    --version              Print the version information

Access the array of devices within an app: Kernel.modules.hid.devices

Web Bluetooth

Expand Web Bluetooth

Experimental Web Bluetooth API features are limited in browser support at this time.

The bluetooth command doesn't do much except pair and maintain a list of devices.

Usage:
    bluetooth devices            List paired bluetooth devices
    bluetooth pair <options>     Request bluetooth device (blank for user choice)

  Options:
    --help                 Print this help message
    --name                 Specify a friendly name for the bluetooth device
    --version              Print the version information

Access the array of devices within an app: Kernel.modules.bluetooth.devices

TODO

Expand TODO

There's a lot to do... please help. 😅
IO piping
Tab completion
Typescriptify everything
Finish internationalization/translations
Decoupling of most built-in modules into their own packages
Unified WASM handling
Rewrite expensive core modules using Emscripten
Improve security/isolation
Some apps are just placeholders; flesh them out
Modify command interfaces to conform to IEEE Std 1003.1-2017
Add more things to the TODO list

Can it do thing?

If it's not in this README or not readily apparent in the included apps, the answer is probably not yet. PR's are always welcome and encouraged. Let's talk about it on Discord! But remember, you can always just use Javascript!

Better yet, if you can make it do the thing, please submit a PR! This project will never grow without a thriving community of developers!

Further Documentation

You can find the full API reference and other tutorials at https://docs.web3os.sh

Questions? Check out the discussion forums

Problems? Search the issues

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

Features

Disclaimer

Help Wanted

User Quickstart

Developer Quickstart

Autostart

Globals

Shortcuts

Scripting

Web3os Package Manager

Official Apps

Three (OS Assistant)

Kernel Interface

App Structure

Metal (@web3os-core/metal)

WebUSB

WebHID

Web Bluetooth

TODO

Can it do thing?

Further Documentation

Files

README.md

Latest commit

History

README.md

File metadata and controls

Features

Disclaimer

Help Wanted

User Quickstart

Developer Quickstart

Autostart

Globals

Shortcuts

Scripting

Web3os Package Manager

Official Apps

Three (OS Assistant)

Kernel Interface

App Structure

Metal (@web3os-core/metal)

WebUSB

WebHID

Web Bluetooth

TODO

Can it do thing?

Further Documentation