Quick Start with HyperBEAM

Welcome to building on HyperBEAM, the decentralized operating system built on AO.

HyperBEAM leverages the permanent storage of Arweave with the flexible, scalable computation enabled by the AO-Core protocol and its HyperBEAM implementation. This allows you to create truly autonomous applications, agents, and services that run trustlessly and permissionlessly.

Thinking in HyperBEAM

Your serverless function can be a simple Lua script, or it can be a more complex WASM module. It will be deployed as a process on HyperBEAM whose state is stored on Arweave and is cached on HyperBEAM nodes. This gives you both benefits: permanence and speed.

At its heart, building on HyperBEAM involves:

1. Processes: Think of these as independent programs or stateful contracts. Each process has a unique ID and maintains its own state.
2. Messages: You interact with processes by sending them messages. These messages trigger computations, update state, or cause the process to interact with other processes or the outside world.

Messages are processed by Devices, which define how the computation happens (e.g., running WASM code, executing Lua scripts, managing state transitions).

Starting aos: Your Development Environment

The primary tool for interacting with AO and developing processes is aos, a command-line interface and development environment.

npmbunpnpm

npm i -g https://get_ao.arweave.net

bun install -g https://get_ao.arweave.net

pnpm add -g https://get_ao.arweave.net

While you don't need to run a HyperBEAM node yourself, you do need to connect to one to interact with the network during development.

To start aos, simply run the command in your terminal:

aos --mainnet "https://dev-router.forward.computer" myMainnetProcess

This connects you to an interactive Lua environment running within a process on the AO network. This process acts as your command-line interface (CLI) to the AO network, allowing you to interact with other processes, manage your wallet, and develop new AO processes. When you specify --mainnet <URL>, it connects to the genesis_wasm device running on the HyperBEAM node at the supplied URL.

Note

What aos is doing:

• Connecting: Establishes a connection from your terminal to a remote process running the aos environment.
• Loading Wallet: Looks for a default Arweave key file (usually ~/.aos.json or specified via arguments) to load into the remote process context for signing outgoing messages.
• Providing Interface: Gives you a Lua prompt (default@aos-2.0.6>) within the remote process where you can:
  • Load code for new persistent processes on the network.
  • Send messages to existing network processes.
  • Inspect process state.
  • Manage your local environment.

Initializing a Variable

From the aos prompt, you can assign a variable. Let's assign a basic Lua process that just holds some data:

default@aos-2.0.6> myVariable = "Hello from aos!"

This assigns the string "Hello from aos!" to the variable myVariable within the current process's Lua environment.

default@aos-2.0.6> myVariable
Hello from aos!

This displays the content of myVariable.

Sending Your First Message

Let's send our variable to another process.

default@aos-2.0.6> Send({ Target = ao.id, Data = myVariable })

You should see the following output:

New Message From <your-process-id>: Data = Hello from aos!

Creating Your First Handler

Handlers are decentralized functions that can be triggered by messages.

Follow these steps to create and interact with your first message handler in AO:

1. Create a Lua File to Handle Messages: Create a new file named main.lua in your local directory and add the following Lua code:

   Handlers.add(
     "HelloWorld",
     function(msg)
       print("Handler triggered by message from: " .. msg.From)
       msg.reply({ Data = "Hello back from your process!" })
     end
   )
   
   print("HelloWorld handler loaded.")
   

   • `