xrsh

click here for the website / hosted repo

XRSH Manual

Documentation for XRSH users can be found here

TIP: this is also available by typing ctrl/cmd+a+0 or man xrsh inside XRSH

Wiki / Roadmap

See the wiki here

Install

NOTE: installation is optional: just surf to the public version here

For local use: download the crossplatform xrsh.com executable [checksum]:

1. [linux/mac only] run chmod +x xrsh.com in the console
2. run ./xrsh.com in the console
3. xrsh opens in your browser at https://127.0.0.1:8080
4. profit!

pass -p XXXX to specify port (default:8080)

Installation guides

run standalone binary

1. Download xrsh.com
2. optional: run unzip xrsh.com to verify repository contents
3. run chmod +x xrsh.com in your console (only linux/mac)
4. run ./xrsh.com in (any) shell
5. Profit! ✔

install using nixos

NIX is a convenient way to install or develop xrsh:

1. nix-shell -p xrsh thttpd
2. run it (thttpd -p 8080 -d /nix/store/5q4vd50gmh52jh48z62ln1j05xzfh1fz-xrsh-0.142 e.g.)
3. point your browser to localhost:8080
4. profit!

run OCI container [podman/docker]

1. $(which podman || which docker) run -p 8080:8080 docker.io/coderofsalvation/xrsh
2. point your browser to localhost:8080
3. profit!

NOTE 1: to add files use the -D <dir> overlay webroot parameter.

NOTE 2: to enable SSL and add (iso)file try something like this:

$ mkdir data
$ cp ../xrsh.iso data/. # copy custom iso
$ $(which podman || which docker) run -p 8080:8080 -v data/cert:etc/cert -v data:/data docker.io/coderofsalvation/xrsh /xrsh.com -D /data -c 0 -C /etc/cert/cert.pem -K /etc/cert/key.pem

or as an exercise in constructive laziness setup a reverse proxy like zoraxy, go-proxy, [droxy], caddy or nginx-reverse-proxymanager.

run from codeberg.org

(codeberg.org is a nonprofit-backed forgejo instance)

1. create a repository on codeberg.org
2. git push the xrsh repository to it
3. create a pages branchclone
4. push it to the codeberg repository
5. profit! it is now live

more info: https://docs.codeberg.org/codeberg-pages/

run from selfhosted forgejo/gitea instance

1. clone the xrsh xrsh repository locally
2. create a repo on your forgejo instance
3. git push the xrsh to it
4. in your forgejo (docker/nix)-instance symlink it to the public folder (*)
5. point your browser to https://yourforgejo.org/assets/xrsh

* = for example: ln -f git/repositories/yourusername/xrsh gitea/public/assets/.

optionally customize the xrsh yunohost package with your own ISO

install in yunohost

1. search for xrsh in the yunohost application catalog
2. click install
3. profit!

optionally customize the xrsh yunohost package with your own ISO

install with systemd

1. Create a new systemd service file (sudo nano /etc/systemd/system/xrsh.service e.g.)
2. Specify the ExecStart directive to run the xrsh ([Service]\ExecStart=/path/to/xrsh.com -p 8080 e.g.).
3. Enable the service (sudo systemctl enable xrsh.service e.g.)
4. Start the service (sudo systemctl start xrsh.service).
5. Verify the service: sudo systemctl status xrsh.service or netstat -tuln.

run from github

Sigh..good old github times (RIP)..
It used to be a simple webinterface around git in 2008.
These days running a forgejo/gitea instance + CI is literally one cmd away (or hosted by codeberg.org.

Developers

Make sure to clone the repo including submodules (the xrsh-com repo)

$ git clone --recurse-submodules https://forgejo.isvery.ninja/xrsh/xrsh
$ cd xrsh
$ nix-shell  # optional but adviced (to get up and running instantly)

Now serve the repo from a HTTPS webserver (for example run ./make dev)

Eventhough a custom ISO-image can be built, XRSH is buildless software.
The crossplatform binary is just a zip-file with the source (using https://redbean.dev):

build using shellscript

1. Run ./make standalone to package everything into xrsh.com

build using nix

1. nix-build -E "with import <nixpkgs> { }; callPackage ./nix/xrsh-package.nix"
2. optionally see the other nix-files in nix-folder

launch different .iso / modify files

You can specify a different .iso file in various ways:

1. open the xrsh.com as a zip (drag-drop into a zip-manager, or add .zip extension)
2. method 1: overwrite xrsh.iso
3. method 2: open src/index.html and change isoterminal="iso: ./../xrsh.iso" to another file/URL

see developer-section below on building your own iso

• development of components (src/com) takes places in this git submodule
• development of xrsh.iso takes places in this gitsubmodule

IMPORTANT: existing AFRAME apps can embed a barebones XR terminal / REPL like this:

<html>
    <head>
        <script src="https://aframe.io/releases/1.6.0/aframe.min.js"></script>
        <script src="https://xrsh.isvery.ninja/xrsh.js"></script>
    </head>
    <body>
      <a-scene>
          <a-entity isoterminal position="0 1.6 -0.3"></a-entity>
      </a-scene>
      <script>
        document.querySelector('a-scene').addEventListener('isoterminal_init', function(e){

          // (OPTIONAL) override/extend bootmenu-array with your own REPL(s)
          //            see com/isoterminal/feat/boot.REPL.*.js for examples
          ISOTerminal.prototype.boot.menu.push({
            key: "f",
            title: (opts) => `other awesome NLnet FOSS projects ❤️`,
            init: function( mainmenu ){
              window.open('https://nlnet.nl/project/current.html','_blank')
              // return to main menu
              mainmenu()
            },
            keyHandler: function(ch){
              this.send("\n\ryou typed:"+ch) // write to term
            }
          }) 

        })

        // AFRAME exposes THREE too
        console.log(THREE)

      </script>
    </body>
</html>

> this portable version runs without the ISO (which requires wasm-files, longer loadingtimes e.g.)

Building your own ISO

As described in the website documentation you could boot your own ISO distribution (TIP: a filesystem overlay is easier):

$ git clone --recurse-submodules ssh://git@forgejo.isvery.ninja:8222/xrsh/xrsh.git 
$ git clone ssh://git@forgejo.isvery.ninja:8222/xrsh/xrsh-buildroot
$ cd xrsh
$ rm xrsh.iso && ln -fs ../xrsh-buildroot/dist/v86-linux.iso xrsh.iso
$ ./make dev 

You can read the repo-README about (re)building/modifying the iso

Funding

This project is funded through NGI0 Entrust, a fund established by NLnet with financial support from the European Commission's Next Generation Internet program. Learn more at the NLnet project page.

Inspired by

• mimetype hooks: Future of Text's
• xterm
• xr-terminal of Mauve (an amazingly talented dev)
• Fabien Beneout's PIM (the WIKI containing all secrets & ideas in life)