Acurast CLI

Which tool should I use?

CLI — interactive local workflow: new / init / deploy / live. Best for getting started and day-to-day deployments.
SDK — programmatic deploys from your own TypeScript/JavaScript code (CI, backends, custom flows).
Deploy Agent — pay with USDC on Base via x402. Best for AI agents and services without ACU accounts.

Introduction

The Acurast CLI is a command-line tool to deploy and manage apps on the Acurast Cloud. It is built on top of @acurast/sdk, so any deployment workflow available in the CLI can also be driven programmatically from your own code.

Installation

Install the Acurast CLI globally using npm:

npm install -g @acurast/cli

Quick Start

# Create a new project from a template
acurast new my-project

# Initialize configuration (creates acurast.json and .env)
acurast init

# Deploy to Acurast Cloud
acurast deploy

Commands

Command	Description
`new <project-name>`	Create a new Acurast project from a template
`deploy [project]`	Deploy the current project to the Acurast platform
`estimate-fee [project]`	Estimate the fee for the current project
`deployments [arg]`	List, view, and manage deployments
`live [project]`	Run your project on a live-code-processor in real time
`init`	Create an `acurast.json` and `.env` file
`devtools <deployment-id>`	Request a DevTools view key and open the DevTools URL
`open`	Open Acurast resources in your browser
`help [command]`	Display help for a command

Options

-v, --version — Output the version number
-h, --help — Display help for a command

Configuration

Running acurast init creates two files:

acurast.json

This file defines your deployment parameters. Example:

{
  "projects": {
    "example": {
      "projectName": "example",
      "fileUrl": "dist/bundle.js",
      "network": "mainnet",
      "onlyAttestedDevices": true,
      "enableDevtools": false,
      "assignmentStrategy": {
        "type": "Single"
      },
      "execution": {
        "type": "onetime",
        "maxExecutionTimeInMs": 10000
      },
      "maxAllowedStartDelayInMs": 10000,
      "usageLimit": {
        "maxMemory": 0,
        "maxNetworkRequests": 0,
        "maxStorage": 0
      },
      "numberOfReplicas": 64,
      "requiredModules": [],
      "minProcessorReputation": 0,
      "maxCostPerExecution": 100000000000,
      "includeEnvironmentVariables": [],
      "processorWhitelist": [],
      "mutability": "Immutable",
      "reuseKeysFrom": null
    }
  }
}

Configuration Fields

Field	Description
`projectName`	The name of the project
`fileUrl`	Path to the bundled file including all dependencies (e.g., `dist/bundle.js`)
`network`	Network for deployment (e.g., `mainnet`, `canary`)
`onlyAttestedDevices`	Only allow attested devices to run the app
`enableDevtools`	Enable DevTools for the deployment. Defaults to `false`
`startAt`	Start time — either `{ msFromNow: number }` or `{ timestamp: number }`
`assignmentStrategy`	`"Single"` (one set of processors) or `"Competing"` (new processors per execution)
`execution`	`"onetime"` or `"interval"` with `intervalInMs`, `numberOfExecutions`, and `maxExecutionTimeInMs`
`maxAllowedStartDelayInMs`	Maximum allowed start delay in milliseconds
`usageLimit`	Limits for `maxMemory`, `maxNetworkRequests`, and `maxStorage` (in bytes)
`numberOfReplicas`	How many processors run the deployment in parallel
`requiredModules`	Modules the processor must support. Supported values: `"DataEncryption"`, `"LLM"`, `"Shell"`. Defaults to `[]`. When `runtime` is `"Shell"`, `"Shell"` is auto-injected
`runtime`	Runtime used to execute the deployment. `"NodeJSWithBundle"` (default), `"NodeJS"`, or `"Shell"`. See Shell Runtime
`image`	Linux distro image used by the Shell runtime. Required when `runtime` is `"Shell"`. Object: `{ url, sha256 }` (HTTPS `.tar.xz` URL + SHA256). Ignored otherwise
`entrypoint`	Script or binary the processor runs after extracting the Shell image (e.g. `acurast.sh`)
`restartPolicy`	`"no"` (default — run once, no retry) or `"onFailure"` (retry up to 3 times on failure; only the third failure is reported)
`minProcessorReputation`	Minimum required processor reputation
`maxCostPerExecution`	Maximum cost per execution in the smallest denomination of ACU
`includeEnvironmentVariables`	Environment variables from `.env` to pass to the deployment
`processorWhitelist`	Whitelist of processor addresses
`minProcessorVersions`	Minimum processor versions (`android`, `ios`)
`mutability`	`"Immutable"` (default) or `"Mutable"` — controls whether the deployment can be modified after creation
`reuseKeysFrom`	Reuse keys from a previous mutable deployment. Format: `["Acurast", "address", deploymentId]`

.env

Stores secrets and environment variables:

ACURAST_MNEMONIC=abandon abandon about ...
# ACURAST_IPFS_URL=https://api.pinata.cloud
# ACURAST_IPFS_API_KEY=eyJhb...
# ACURAST_RPC=wss://...

Variable	Required	Description
`ACURAST_MNEMONIC`	Yes	Mnemonic for the deployer account. Must have ACU (or cACU on canary). Claim cACU on the faucet
`ACURAST_IPFS_URL`	No	IPFS gateway URL (e.g., `https://api.pinata.cloud`)
`ACURAST_IPFS_API_KEY`	No	API key for the IPFS gateway. Register here
`ACURAST_RPC`	No	Custom RPC URL

Environment Variables

You can pass encrypted environment variables to your deployments. They are encrypted during deployment and only decrypted on the processor at runtime.

1. Add variables to .env:

API_KEY=your-api-key

2. Reference them in acurast.json:

{
  "includeEnvironmentVariables": ["API_KEY"]
}

3. Access them in your code:

const API_KEY = _STD_.env[API_KEY];

For interval-based deployments, you can update environment variables between executions:

acurast deployments <id> --update-env-vars

Deployment Management

Listing and Viewing

# List all deployments
acurast deployments ls

# List deployments on canary network
acurast deployments ls --network canary

# View a specific deployment
acurast deployments <id>

Cleanup

# Clean up old, finished deployments and return unused funds
acurast deployments --cleanup

# Clean up a specific deployment
acurast deployments <id> --cleanup

Updating Mutable Deployments

Deployments created with "mutability": "Mutable" can be updated after creation.

Update Script

acurast deployments update script <deployment-id> <script-ipfs> [--dry-run] [--force]

Example:

acurast deployments update script \
  "Acurast:5CiPPse...DjL:123456" \
  "ipfs://QmNewScriptHash"

Transfer Editor Permissions

acurast deployments update editor <deployment-id> <new-editor-address> [--dry-run] [--force]

Deployment ID Format

Deployment IDs follow the format origin:address:number:

origin — The chain name (currently "Acurast")
address — The deployer's AccountId32 address
number — Sequential deployment number

Example: "Acurast:5CiPPseXPECbkjWCa6MnjNokrgYjMqmKndv2rSnekmSK2DjL:123456"

Find your deployment IDs by running acurast deployments ls.

Live Code

The Live Code feature lets you run your code on a dedicated processor in real time, with immediate feedback including console.log output and errors.

Setup

acurast live --setup

During setup, choose the duration and follow the CLI instructions. After the deployment starts (approximately 5 minutes), run:

acurast live

This executes your project on the live processor using the configuration from acurast init.

Shell Runtime

Set runtime: "Shell" to run a deployment as a native binary inside a Linux distro image on the processor (PRoot-isolated). This unlocks shell scripts, native tooling, and any language you can ship as a Linux binary.

Provide an image (URL + SHA256) and an entrypoint. The CLI embeds the image reference in the deployment manifest and auto-adds the "Shell" required module on-chain.

{
  "projects": {
    "my-shell-project": {
      "projectName": "my-shell-project",
      "fileUrl": "./shell-app",
      "entrypoint": "acurast.sh",
      "runtime": "Shell",
      "image": {
        "url": "https://github.com/termux/proot-distro/releases/download/v4.30.1/ubuntu-questing-aarch64-pd-v4.30.1.tar.xz",
        "sha256": "5ab35b90cd9a9f180656261ba400a135c4c01c2da4b74522118342f985c2d328"
      },
      "restartPolicy": "no",
      "network": "mainnet",
      "onlyAttestedDevices": true,
      "assignmentStrategy": { "type": "Single" },
      "execution": { "type": "onetime", "maxExecutionTimeInMs": 60000 },
      "maxAllowedStartDelayInMs": 10000,
      "usageLimit": { "maxMemory": 0, "maxNetworkRequests": 0, "maxStorage": 0 },
      "numberOfReplicas": 1,
      "requiredModules": [],
      "minProcessorReputation": 0,
      "maxCostPerExecution": 5000000000,
      "includeEnvironmentVariables": [],
      "processorWhitelist": []
    }
  }
}

Supported images: see Termux proot-distro releases.

Environment variables in includeEnvironmentVariables are injected as standard system env vars (no _STD_ API). Host services (deployment metadata, signing, browser control) are exposed via a JSON-RPC API on an abstract Unix socket; the socket name is in the BRIDGE_SOCKET env var.

Key Reuse

The reuseKeysFrom field lets you maintain the same cryptographic keys across deployments. The referenced deployment must be mutable.

{
  "reuseKeysFrom": [
    "Acurast",
    "5CiPPseXPECbkjWCa6MnjNokrgYjMqmKndv2rSnekmSK2DjL",
    123456
  ]
}

Introduction​

Installation​

Quick Start​

Commands​

Options​

Configuration​

acurast.json​

Configuration Fields​

.env​

Environment Variables​

Deployment Management​

Listing and Viewing​

Cleanup​

Updating Mutable Deployments​

Update Script​

Transfer Editor Permissions​

Deployment ID Format​

Live Code​

Setup​

Shell Runtime​

Key Reuse​