Skip to content

Aleph.im VM execution engine

License

MIT, MIT licenses found

Licenses found

MIT
LICENSE
MIT
LICENSE.txt
Notifications You must be signed in to change notification settings

aleph-im/aleph-vm

Folders and files

NameName
Last commit message
Last commit date

Latest commit

bb5d74d · Dec 12, 2024
Nov 20, 2024
Oct 8, 2024
Sep 9, 2024
Oct 9, 2024
Oct 10, 2023
Dec 12, 2024
Dec 3, 2024
Dec 12, 2024
Dec 3, 2024
Apr 26, 2024
Apr 9, 2024
Jun 19, 2024
Jun 19, 2024
Jun 19, 2024
Jul 5, 2022
Mar 14, 2024
May 27, 2021
Nov 20, 2024
Nov 20, 2024
Nov 20, 2023
Dec 12, 2024

Repository files navigation

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
  1. 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
  2. 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
  3. 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

Aleph im VM - Details

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.


aleph.im logo