Aleph-VM

The Aleph-VM project allows you to run programs on Aleph.im.

Aleph-VM is optimized to run programs on demand in a "function-as-as-service", as a response to HTTP requests.

Programs can be written in any language as long as they can run a web server. They benefit from running in their own, customizable Linux virtual environment.

Writing programs in Python using ASGI compatible frameworks ( FastAPI, Django, ...) allows developers to use advanced functionalities not yet available for other languages.

Production install for Aleph-VM

Installation from packages

Head over to the official user doc https://docs.aleph.im/nodes/compute/ on how to run an Aleph.im Compute Resource Node

2. Install Aleph-VM from source

This method is not recommended, except for development and testing. Read the installation document for the various components and the developer documentation.

1. Install the VM-Connector
2. Install the VM-Supervisor.
3. Install and configure a reverse-proxy such as Caddy

Create and run an Aleph Program

Have a look at tutorials/README.md for a tutorial on how to program VMs as a user.

The rest of this document focuses on how to run an Aleph-VM node that hosts and executes the programs.

Developer Setup

Due to aleph-vm’s deep integration with the Linux system, it must be run with root privileges and configured specifically for Linux. It is strongly recommended to deploy aleph-vm on a dedicated machine or a cloud-based server to ensure security and stability.

Note: aleph-vm does not run on macOS or Windows, including for testing purposes.

Recommended Development Environment

A typical setup for developing aleph-vm involves:

1. Cloning the repository on your local machine for code editing.
2. Setting up a remote Linux server for deployment and testing.

You can synchronize changes to the remote server using tools like rsync or PyCharm’s Remote Interpreter feature.

Remote Development Deployment

To deploy aleph-vm for development on a remote server, we start with the Debian package as it includes essential binaries like firecracker and sevctl, system configuration, and dependencies.

1. Run the vm-connector.

The vm-connector need to run for aleph-vm to works, even when running py.test.

Unless your focus is developing the VM-Connector, using the Docker image is easier. See the VM-Connector README for more details.

docker run -d -p 127.0.0.1:4021:4021/tcp --restart=always --name vm-connector alephim/vm-connector:alpha

2. Install the Debian Package Replace 1.2.0 with the latest release version.

   On Debian 12 (Bookworm):

   wget -P /opt https://github.com/aleph-im/aleph-vm/releases/download/1.2.0/aleph-vm.debian-12.deb
   sudo apt install /opt/aleph-vm.debian-12.deb

   On Ubuntu 22.04 (Jammy Jellyfish):

   sudo wget -P /opt https://github.com/aleph-im/aleph-vm/releases/download/1.2.0/aleph-vm.ubuntu-22.04.deb
   sudo apt install /opt/aleph-vm.ubuntu-22.04.deb

   On Ubuntu 24.04 (Noble Numbat):

   sudo wget -P /opt https://github.com/aleph-im/aleph-vm/releases/download/1.2.0/aleph-vm.ubuntu-24.04.deb
   sudo apt install /opt/aleph-vm.ubuntu-24.04.deb

3. Disable Systemd Service
   To prevent conflicts, deactivate the system version of aleph-vm by disabling its systemd service.

   sudo systemctl disable aleph-vm-supervisor.service

4. Clone the Repository and Set Up a Virtual Environment

   • Clone the aleph-vm repository to your development environment.
   • Create a virtual environment to manage dependencies.

   Inside the virtual environment, run:

   pip install -e .

   This installs aleph-vm in "editable" mode within the virtual environment, allowing you to use the aleph-vm command directly during development.

Testing

See Testinc doc

Architecture

VM Supervisor (also called Orchestrator)

Actually runs the programs in a secure environment on virtualization enabled systems.

See vm_supervisor/README.md.

VM Connector

Assist with operations related to the Aleph network.

See vm_connector/README.md.

---