CoWasm is a terminal-shaped Python runtime in the browser, built for SageMath

The differentiator is a Unix runtime, not scientific Python

CoWasm, or Collaborative WebAssembly, goes far beyond just Python, and the project says the collaboration aspects will be part of CoCalc at some point in the future. CoWasm will support various technologies, such as libgit2 and realtime sync, that are important foundations for collaboration.

The north star is stated plainly: CoWasm is a browser-native Unix/Python runtime for serious mathematics, with Sagelite and SageMath as the defining long-term applications.

The reasoning about Pyodide is the most useful part of the README, because it defines the project's negative space. Pyodide is the main reference point for browser scientific Python, and CoWasm should instead focus on the parts of mathematical computing that need a terminal-shaped, filesystem-shaped, interruptible runtime: exact algebra, number theory, symbolic computation, mathematical package dependencies, and eventually a useful subset of SageMath in the browser without a full Linux emulator.

The long-term differentiator is stated as a two line comparison. Pyodide is scientific Python in the browser, and CoWasm is pure mathematics and SageMath-style computation in the browser.

That framing explains the architecture. A terminal you can interrupt and a filesystem you can address are prerequisites for computational algebra systems, and a scientific Python notebook is not.

Shared libraries, a real shell, and memfs instead of a browser filesystem

Three implementation choices separate CoWasm from the other WebAssembly toolchains, and the README lists them as differences rather than features.

First, unlike WebAssembly.sh and wapm.io but similar to Pyodide, CoWasm makes very heavy use of shared dynamic libraries, for example -fPIC code, which is only possible because of a plugin contributed from emscripten to LLVM. The project explains what the name means: the Co in CoWasm suggests collaboration or sharing, which also reflects how the binaries in the project are structured.

Second, it uses actual editline, similar to readline, instead of a JavaScript terminal. Unlike other WebAssembly shells, it uses a real command-line shell, dash, the Debian Almquist Shell, and there is a user space including ports of many coreutils, for example ls, head and tail.

Third, unlike emscripten, the project uses modern TypeScript, the code is more modular, and existing components are used where possible, the Node.js memfs project being the example given, instead of writing their own.

The design constraint stated after that is about reach rather than about any one platform: CoWasm should run on servers, desktops such as an Electron app, iPad and iOS apps, and in web browsers, not just in the browser like emscripten and not just on servers like wasmer.

Shared libraries plus a real shell plus memfs is what makes an interruptible, filesystem-shaped runtime possible in a sandbox, and it is why the project describes itself as a foundation rather than an application.

Five packages, and the SageMath port that is not finished

The repository is organised as a set of subdirectories that each contain packages, and the five of them divide the work cleanly.

core holds the core functionality, including dynamic linking, a WASI implementation, OpenSSL, and nontrivial POSIX extensions to Node.js written in Zig. The documentation compares it to emscripten.org, which is a fair comparison since that is the layer emscripten plays.

python is a WebAssembly build of Python along with some nontrivial scientific libraries, compared to pyodide.org.

web holds examples of how to use the other packages in web applications, and it includes building cowasm.org itself.

desktop is a native Electron app that provides a sandboxed WebAssembly Python terminal running on your native filesystem.

sagemath is the beginning of a port of SageMath to WebAssembly, and the README is careful that vast amounts of work remain and that this is the long-term north star rather than a near-term promise.

The Python package has its own detail. python-wasm, published on npm, is a build of Python for WebAssembly that supports both servers and browsers, and it also supports extension modules such as numpy.

So a realistic near-term use of CoWasm is python-wasm with numpy, and the SageMath vision is what the architecture is being built towards.

Building it needs a Unix toolchain, and Windows means Docker

The build documentation is explicit about where CoWasm is supported and tested: x86 macOS and aarch64 macOS on Apple Silicon M1, and x86 and aarch64 Linux.

The prerequisites are Node.js version at least 16.x, pnpm and several standard development tools. On macOS that means installing the XCode command line tools. On a Linux apt-based system such as Ubuntu 22.04 the dependency list is long.

sudo apt-get update && sudo apt-get install git make cmake curl dpkg-dev m4 yasm texinfo python-is-python3 libtool tcl zip libncurses-dev

Node and pnpm can be added on Ubuntu as well.

     sudo curl -sL https://deb.nodesource.com/setup_18.x | bash - \
  && sudo apt-get install -y nodejs \
  && curl -fsSL https://get.pnpm.io/install.sh | sh -

The RPM based list for Fedora 37 and the Arch list are similar in shape, and the Arch note is worth remembering: pnpm is not in the Arch official package sets, so you may want to install it from the AUR.

pacman -Sy binutils git nodejs npm cmake curl m4 yasm texinfo python libtool tcl zip unzip patch binutils diffutils

The Windows answer is the blunt one: currently, the only way to build CoWasm from source on MS Windows is to use a Docker container running Linux, and using WSL2 maybe works but is too slow.

That is a real constraint for a project whose stated goal includes running on desktops, since a Windows developer is pushed to a container.

The Makefile builds each package group and tests it separately

The build system is plain make with one wrapper script, and the targets mirror the package layout.

There is a fetch-sources target, an audit-sources target, and then an all target for every package group at once. Each group also gets its own build, test and clean targets, so core, python, web, desktop and sagemath can be built independently.

The targets for the groups are named after the group, so a core build is the core target and the Python tests are the test-python target.

The test target for a group depends on building it first, and the top level test-packages target depends on packages. In other words, the test suite is run per package, not once at the end.

There is a python-supported variant, and the Makefile shows why it exists. The variable PYTHON_DISABLED is empty in the file you see, and PYTHON_SUPPORTED is computed by filtering it out, so the supported set is derived from a disable list rather than hard coded. That is the mechanism for excluding a Python package that does not build on a given platform.

The Makefile also puts the bin directory and the core/zig/dist directory on the PATH, which is how the built tools become callable from the build scripts.

The Dockerfile pins Node 18 and runs the test suite

The Dockerfile exists to make the build predictable, and its stated goal is that this fully works on both x86_64 and aarch64 hosts and results in /cowasm having everything built with the test suite passing.

The base is ubuntu:22.04 with a noninteractive frontend and C.UTF-8 locale, and the maintainer is labelled as William Stein of sagemath.com.

The dependency layer installs the same apt toolchain the documentation lists for Ubuntu, then replaces the distribution's Node with a pinned one. The comment is explicit about why: we specify a particular version of node.js for reproducibility, not because it is needed for some reason. The keyring is created for the NodeSource repository, NODE_MAJOR is set to 18, and the exact package nodejs=18.17.1-1nodesource1 is installed and then held with apt-mark, and npm and pnpm are installed globally.

The source step clones the repository, checks out a commit that defaults to HEAD, and runs make.

RUN  git clone https://github.com/sagemathinc/cowasm \
  && cd cowasm \
  && git checkout ${commit:-HEAD} \
  && make

Then the PATH is extended so the built Python is on it, and the last step runs the test suite.

RUN echo "export PATH=/python-wasm/bin/:$PATH" >> /root/.bashrc
RUN cd cowasm && make test

The build argument for the commit is what makes this usable in CI, since a build can be pinned to a specific revision of the tree.

Licensing is the reason other projects can build on it

There is no business-unfriendly GPL code in CoWasm, according to the documentation, and CoWasm itself is extremely liberally licensed and business-friendly. The licence of all new code and most components is 3-clause BSD.

That is not a legal detail here, it is the reason the project exists in this shape. The README says CoWasm will serve as a foundation for other projects with more restrictive licences, and it names two of them. CoCalc will build on top of CoWasm to provide a graphical interface and real-time collaboration, and that will be a commercial product. Products like GP and PARI SageMath will build on CoWasm to provide GPL-licensed mathematics software.

So the dependency direction runs from permissive to restrictive, which is the opposite of the usual arrangement and is the reason a company and a GPL project can both depend on the same runtime.

The other licensing statement worth reading is about the components CoWasm does not write. The project says most of the underlying software it builds on are extremely stable and mature, that Zig is less stable but is mostly used for its cross-compilation support and for packaging clang, llvm and musl-libc, and that many other components such as Python, Dash and Numpy are extremely mature multi-decade-old projects. Other components, such as memfs, are described as libraries with 10M+ downloads per week that are heavily used in production.

The Zig dependency is the one real instability, and the project is candid about it.

Editorial conclusion

CoWasm fits a team that wants exact mathematical computing, including SageMath-style work, to run in a browser or on a server without shipping a full Linux emulator, because the shared library architecture and the real shell are what make a Unix-shaped runtime possible in WebAssembly. It does not fit a team that wants SageMath working in a browser next quarter, since the sagemath package is described as the beginning of a port with vast amounts of work remaining. Before adopting it, build the core and python packages on a supported platform and read the python README, because the Python layer is the part you are most likely to depend on, and decide whether the full SageMath target belongs in your plan or in someone else's.

Frequently asked questions

Official sources

1. Issues
2. License: BSD-3-Clause
3. Project website
4. README
5. sagemathinc/cowasm on GitHub