github.com/Acurast/acurast-cli @v0.9.1

Acurast CLI

Deploy apps on the Acurast Cloud

Intro

The Acurast CLI helps you to deploy apps on the Acurast Cloud.

Installation

To install the Acurast CLI, you can use npm:

npm install -g @acurast/cli

Usage

To use the Acurast CLI, type acurast followed by any of the available options or commands.

Options

• -v, --version - Output the version number.
• -h, --help - Display help for command.

Commands

• new <project-name> - Create a new Acurast project from a template.
• deploy [options] [project] - Deploy the current project to the Acurast platform.
• cancel <deployment-id> [options] - Cancel (deregister) a deployment on-chain and return any unused locked funds.
• estimate-fee [options] [project] - Estimate the fee for the current project.
• deployments [arg] [options] - List, view, and manage deployments.
• deployments ls or deployments list - List all your deployments.
• deployments <id> - View details of a specific deployment.
• deployments <id> --update-env-vars - Update environment variables for a deployment.
• deployments --cleanup - Clean up old, finished deployments.
• deployments <id> --cleanup - Clean up a specific deployment.
• deployments update script <deployment-id> <script-ipfs> [options] - Update the script of a mutable deployment.
• deployments update editor <deployment-id> <new-editor-address> [options] - Transfer editor permissions for a mutable deployment.
• live [options] [project] - Setup a "live-code-processor" and run your project on the processor in real time.
• init - Create an acurast.json file and .env file.
• devtools <deployment-id> - Request a DevTools view key and print the URL for a deployment.
• open - Open the Acurast resources in your browser.
• help [command] - Display help for command.

Configuration

Example Configuration

The acurast.json file is generated by running acurast init. Here is an example configuration:

{
  "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
    }
  }
}

This is the configuration that is read when acurast deploy is called and the app is deployed according to those parameters.

Additionaly, a .env file is generated that will hold some of the secrets to deploy the app, and also any environmnet variables that you may want to add to your deployment.

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

Configuration Details

acurast.json

• projectName: The name of the project.
• fileUrl: The path to the bundled file, including all dependencies (e.g., dist/bundle.js).
• network: The network on which the project will be deployed. One of mainnet, canary, or devnet. See Networks for endpoint defaults and how to override them via env vars.
• onlyAttestedDevices: A boolean to specify if only attested devices are allowed to run the app.
• enableDevtools: A boolean to enable DevTools for the deployment. When enabled, console logs from processor executions are forwarded to the DevTools dashboard. Defaults to false.
• startAt: The start time of the deployment.
• msFromNow: The deployment will start the specified number of milliseconds from now.
• timestamp: The deployment will start at the specified timestamp.
• assignmentStrategy: Defines the assignment strategy, which can be:
• type: AssignmentStrategyVariant.Single: Assigns one set of processors for a deployment. If instantMatch is provided, specifies processors and maximum allowed start delay:
  • processor: Processor address.
  • maxAllowedStartDelayInMs: Maximum allowed start delay in milliseconds.
  • See Instant match for a full example; the repository’s acurast.json also defines a test-instant-match project you can copy from.
• type: AssignmentStrategyVariant.Competing: Assigns a new set of processors for each execution.
• execution: Specifies the execution details, which can be:
• type: 'onetime'`: Run the deployment only once.
  • maxExecutionTimeInMs: Maximum execution time in milliseconds.
• type: 'interval'`: Multiple executions for the deployment.
  • intervalInMs: Interval in milliseconds between each execution start.
  • numberOfExecutions: The number of executions.
  • maxExecutionTimeInMs: Maximum execution time for each execution in milliseconds. If not specified, the full duration of the interval will be used (minus a 10s buffer). It is recommended to set this to at least 10s less than intervalInMs.
  • maxAllowedStartDelayInMs: Specifies the maximum allowed start delay (relative to the starting time) of the deployment in milliseconds.
• usageLimit: The usage limits for the deployment:
• maxMemory: Maximum memory usage in bytes.
• maxNetworkRequests: Maximum number of network requests.
• maxStorage: Maximum storage usage in bytes.
• numberOfReplicas: The number of replicas, specifying how many processors will run the deployment in parallel.
• requiredModules: Modules that the processor needs to support to run the deployment. Supported values: "DataEncryption", "LLM", "Shell". Defaults to []. When runtime is "Shell", "Shell" is auto-injected.
• runtime: The runtime environment used to execute the deployment.
• "NodeJSWithBundle" (default): Node.js, bundled file deployment.
• "NodeJS": Node.js, single-file deployment.
• "Shell": Native binary inside a Linux distro image, isolated via PRoot. See Shell Runtime.
• image: Linux distro image used by the Shell runtime. Required when runtime is "Shell". Ignored otherwise.
• url: HTTPS URL of a .tar.xz distro image (see Termux proot-distro for supported images).
• sha256: SHA256 hash of the image, used by the processor to verify the download.
• minProcessorReputation: The minimum required reputation of the processor.
• maxCostPerExecution: The maximum cost per execution in the smallest denomination of ACU.
• includeEnvironmentVariables: An array of environment variables in the .env file that will be passed to the deployment.
• processorWhitelist: A whitelist of processors that can be used for the deployment.
• minProcessorVersions: The minimum processor versions that will be used for the deployment.
• android: The minimum Android version.
• ios: The minimum iOS version.
• mutability: The mutability of the deployment. Controls whether the deployment can be modified after creation.
• "Immutable": The deployment cannot be modified after creation (default).
• "Mutable": The deployment can be modified after creation.
• reuseKeysFrom: An optional array that allows reusing keys from a previous deployment, if that deployment was set to "Mutable". Format: [MultiOrigin, string, number] where:
• First element: The origin chain (currently only "Acurast" is supported)
• Second element: The address of the original deployer
• Third element: The deployment ID
• Example: ["Acurast", "5CiPPseXPECbkjWCa6MnjNokrgYjMqmKndv2rSnekmSK2DjL", 123456]
• benchmarkFilters (optional): Minimum benchmark requirements used to filter eligible processors.
• minRamTotalBytes: Minimum total RAM in bytes.
• minCpuSingleCoreScore: Minimum single-core CPU score.
• minCpuMultiCoreScore: Minimum multi-core CPU score.
• minStorageAvailBytes: Minimum available storage in bytes.
• poolIds (advanced): Override compute-pallet benchmark pool IDs.

Benchmark Filters

You can constrain deployments to processors that satisfy minimum benchmark values. Benchmark filters can be configured in acurast.json and/or passed via deploy flags.

Config example:

{
  "projects": {
    "example": {
      "benchmarkFilters": {
        "minRamTotalBytes": 4000000000,
        "minCpuSingleCoreScore": 1000,
        "minCpuMultiCoreScore": 3000,
        "minStorageAvailBytes": 64000000000
      }
    }
  }
}

Deploy flag examples (can be combined):

acurast deploy --min-memory 4GB --min-cpu-score 1000 --min-storage 64GB --min-cpu-multi-score 3000

Notes:

• CLI flags merge with benchmarkFilters from acurast.json.
• --min-memory and --min-storage accept human-readable byte sizes (for example 4GB, 512MiB).
• During deploy, matcher check validates whether enough processors match at the current reward.
• Per-processor address lists are shown from on-chain acurastMarketplace.assignedProcessors after match.

.env

ACURAST_MNEMONIC: The mnemonic used to deploy the app. Make sure the account has some ACU (or cACU for canary network)! You can claim cACU on the faucet for canary testing. ACURAST_IPFS_URL (optional): The URL of the IPFS gateway, eg. https://api.pinata.cloud. ACURAST_IPFS_API_KEY (optional): The API key to access the IPFS gateway. You can register here to get an API key. ACURAST_RPC (optional, deprecated): Set an RPC URL to connect to. Kept for backward compatibility — prefer ACURAST_MAINNET_RPC.

Networks

The CLI supports three networks: mainnet (default), canary, and devnet. Set "network" in your acurast.json project entry, or pass --network to commands that accept it (acurast deployments ...).

Each network resolves an RPC endpoint, a matcher URL, and an indexer (with API key). The defaults below ship with the CLI; set the matching env var to override.

Network	Purpose	RPC default	Faucet
mainnet	Production, real ACU	wss://archive.mainnet.acurast.com	n/a (see docs to get ACU)
canary	Public test network	wss://canarynet-ws-1.acurast-h-server-2.papers.tech	https://faucet.acurast.com
devnet	Internal/staging dev environment	wss://acurast-devnet-ws.prod.gke.papers.tech	n/a (request from Acurast)

RPC overrides

Env var	Network applied to	Default
ACURAST_MAINNET_RPC	mainnet	wss://archive.mainnet.acurast.com
ACURAST_RPC	mainnet (legacy)	same as above; honoured when ACURAST_MAINNET_RPC unset
ACURAST_CANARY_RPC	canary	wss://canarynet-ws-1.acurast-h-server-2.papers.tech
ACURAST_DEVNET_RPC	devnet	wss://acurast-devnet-ws.prod.gke.papers.tech

The connected RPC URL is written to .acurast/acurast.log (file log) on every connection — useful when debugging which endpoint a command actually used.

Matcher overrides

The matcher API provides live processor pricing. If unset (or unreachable), the CLI falls back to a static fee estimate.

Env var	Network	Default
ACURAST_MAINNET_MATCHER	mainnet	https://matcher.mainnet.acurast.com
ACURAST_CANARY_MATCHER	canary	https://matcher.canary.acurast.com
ACURAST_DEVNET_MATCHER	devnet	unset — set this if a devnet matcher is available

Indexer overrides

The indexer powers acurast deployments ls. Devnet has no public default — set the env vars below if you need to list deployments on devnet.

Env var	Network	Default
ACURAST_MAINNET_INDEXER	mainnet	https://dev.indexer.mainnet.acurast.com/api/v1/rpc