AO Compute Unit (CU)

Overview

An AO Compute Unit (CU) is a critical component in the AO ecosystem responsible for executing AO processes and maintaining their state. CUs serve as the computational backbone of the AO network by:

Processing Messages: CUs receive and process messages sent to AO processes
Executing WASM Modules: CUs run the WebAssembly (WASM) code that defines process behavior
Maintaining State: CUs track and update the state of AO processes
Creating Checkpoints: CUs periodically save process state to the Arweave network as checkpoints

Running a CU alongside your gateway allows you to:

Process AO requests locally rather than relying on external services
Improve response times for AO-related queries
Contribute computational resources to the AO network
Ensure your gateway has reliable access to AO functionality

For more detailed information about Compute Units, please refer to the AO Cookbook: Units.

System Requirements

Before deploying a CU, ensure your system meets the following requirements:

Recommended: At least 16GB RAM for optimal CU operation
Minimum: 4GB RAM is possible with adjusted memory limits (see resource allocation settings)
At least 100GB disk space dedicated to CU operation
These requirements are separate from your gateway requirements

Resource Requirements

Running a CU is resource-intensive. Make sure your system has sufficient resources to handle both the gateway and the CU. While you can run a CU with less than the recommended RAM, you'll need to adjust the memory limits accordingly.

Deploying an AO CU

Navigate to Gateway Directory

First, navigate to the root directory of your gateway:

cd /path/to/your/gateway

Configure Environment Variables

Copy the example environment file:

cp .env.ao.example .env.ao

Default .env.ao.example Contents

The default .env.ao.example file contains the following settings:

CU_WALLET='[wallet json here]'
PROCESS_CHECKPOINT_TRUSTED_OWNERS=fcoN_xJeisVsPXA-trzVAuIiqO3ydLQxM-L4XbrQKzY
GATEWAY_URL=http://envoy:3000
UPLOADER_URL=http://envoy:3000/bundler

These default settings are configured to work with a gateway running on the same machine, but you'll need to modify them as described below.

Open the .env.ao file in your preferred text editor:

nano .env.ao

Configure the following settings:

CU_WALLET: Replace '[wallet json here]' with the JSON from an Arweave wallet.

JSON Format
The entire JSON must be placed on a single line for proper registration.
PROCESS_CHECKPOINT_TRUSTED_OWNERS: This is a comma-separated list of trusted wallet addresses:
```
PROCESS_CHECKPOINT_TRUSTED_OWNERS=fcoN_xJeisVsPXA-trzVAuIiqO3ydLQxM-L4XbrQKzY
```
Adding Your Own Wallet
If you are uploading your own checkpoints, you should add your own CU wallet address after the default value, separated by a comma:
PROCESS_CHECKPOINT_TRUSTED_OWNERS=fcoN_xJeisVsPXA-trzVAuIiqO3ydLQxM-L4XbrQKzY,YOUR_WALLET_ADDRESS_HERE
This allows your CU to trust checkpoints from both the official source and your own wallet.
GATEWAY_URL: By default, this is set to use your own gateway:
```
GATEWAY_URL=http://envoy:3000
```
A gateway must be set to index all ANS-104 data items from AO or the CU will not operate properly. Most users will want to set this to:
```
GATEWAY_URL=https://arweave.net
```
UPLOADER_URL: By default, this is set to use a bundler sidecar run by your gateway:
```
UPLOADER_URL=http://envoy:3000/bundler
```
Important: Checkpoint Uploads Require Payment
Checkpoints are uploaded to Arweave, so the upload must be paid for. You must ensure your wallet has sufficient funds: - If using https://up.arweave.net (recommended), your CU_WALLET must contain Turbo Credits - If using your own bundler or another service, you'll need the appropriate token (AR or other) - Without proper funding, checkpoints will fail to upload and your CU may not function correctly

The simplest option for most users is to use:
```
UPLOADER_URL=https://up.arweave.net
```
This requires your CU_WALLET to contain Turbo Credits.
Optional: Disable Checkpoint Creation: If you want to disable checkpoint uploads, add:
```
DISABLE_PROCESS_CHECKPOINT_CREATION=true
```

Example of a Completed .env.ao File

Here's an example of what your completed .env.ao file might look like with common settings:

CU_WALLET='{"kty":"RSA","e":"AQAB","n":"mYM07..."}'
PROCESS_CHECKPOINT_TRUSTED_OWNERS=fcoN_xJeisVsPXA-trzVAuIiqO3ydLQxM-L4XbrQKzY
GATEWAY_URL=https://arweave.net
UPLOADER_URL=https://up.arweave.net

After making your changes, save and exit the nano editor:

Press Ctrl+X to exit
Press Y to confirm saving changes
Press Enter to confirm the filename

Optional Resource Allocation Settings

You can fine-tune the CU's resource usage by adding these optional environment variables:

PROCESS_WASM_MEMORY_MAX_LIMIT: Sets the maximum memory limit (in bytes) for WASM processes.
```
PROCESS_WASM_MEMORY_MAX_LIMIT=17179869184  # 16GB (16 * 1024^3)
```
Important Memory Requirement
To work with the AR.IO process, PROCESS_WASM_MEMORY_MAX_LIMIT must be at least 17179869184 (16GB).
Note: This doesn't mean your server needs 16GB of RAM. This is the maximum memory limit the CU will support for processes. Most processes don't use their maximum allocated memory.
You can set this value to 16GB even if your server only has 4GB of RAM. However, if a process requires more memory than your server has available, the CU will fail when evaluating messages that need more memory.
WASM_EVALUATION_MAX_WORKERS: Sets the maximum number of worker threads for WASM evaluation.
```
WASM_EVALUATION_MAX_WORKERS=4  # Example: Use 4 worker threads
```
Worker Thread Configuration
This will default to (available CPUs - 1) if not specified. If you're running a gateway and unbundling on the same server, consider setting this to 2 or less to avoid overloading your CPU.
PROCESS_WASM_COMPUTE_MAX_LIMIT: The maximum Compute-Limit, in bytes, supported for ao processes (defaults to 9 billion)
```
PROCESS_WASM_COMPUTE_MAX_LIMIT=9000000000
```

NODE_OPTIONS: Sets Node.js memory allocation for the Docker container.

NODE_OPTIONS=--max-old-space-size=8192  # Example: 8GB for Node.js heap

Resource Tuning

Start with conservative values and monitor performance. You can adjust these settings based on your system's capabilities and the CU's performance.

Start the CU Container

Once your environment file is configured, start the CU container:

docker compose --env-file .env.ao -f docker-compose.ao.yaml up -d

This command uses the following flags:

--env-file .env.ao: Specifies the environment file to use
-f docker-compose.ao.yaml: Specifies the Docker Compose file to use
up: Creates and starts the containers
-d: Runs containers in detached mode (background)

Check the Logs

To check the logs of your CU container:

docker compose -f docker-compose.ao.yaml logs -f --tail=20

This command uses the following flags:

-f: Follows the log output (continuous display)
--tail=20: Shows only the last 20 lines of logs

Exit the logs by pressing Ctrl+C.

Connecting Your Gateway to the CU

To make your gateway use your local CU:

Add the following line to your gateway's .env file:
```
AO_CU_URL=http://ao-cu:6363
```
This assumes the CU is running on the same machine as the gateway.

Restart your gateway:

docker compose down
docker compose up -d

CU Activation

A CU won't do anything until requests are being made of it. By connecting your gateway to the CU, you'll start generating these requests.

Accessing Your CU

Once properly set up and connected to your gateway, you can access your CU via:

https://<your-gateway-domain>/ao/cu

This endpoint allows you to interact with your CU directly through your gateway's domain.

Important Notes

Initial Processing Time: A CU will need to process AO history before it can give valid responses. This process can take several hours.
Gateway Fallback: A gateway on release 27 or above will fallback to arweave.net if its default CU is not responding quickly enough, so gateway operations will not be significantly impacted during the initial processing.
Monitoring Progress: Check the CU logs after pointing a gateway at it to watch the process of working through AO history:
```
docker compose -f docker-compose.ao.yaml logs -f --tail=20
```
Resource Usage: Running a CU is resource-intensive. Monitor your system's performance to ensure it can handle both the gateway and CU workloads.

Useful Docker Commands

Monitor and manage your AO Compute Unit with these commands:

# View all running services
docker ps

# Start CU container with environment file
docker compose --env-file .env.ao -f docker-compose.ao.yaml up -d

# Stop CU container
docker compose -f docker-compose.ao.yaml down

# Pull latest CU images
docker compose -f docker-compose.ao.yaml pull

# Follow CU logs
docker compose -f docker-compose.ao.yaml logs -f --tail=20

# Check CU container status
docker compose -f docker-compose.ao.yaml ps

# Restart CU container
docker compose -f docker-compose.ao.yaml restart

# View CU logs without following
docker compose -f docker-compose.ao.yaml logs --tail=50

# Start CU in foreground (for debugging)
docker compose --env-file .env.ao -f docker-compose.ao.yaml up