Skip to content
acurast.dev

Let your agent deploy

One page of instructions any AI agent can read: how to run the Acurast CLI without prompts, what to ask you first, and how to clean up.

Give your agent this

Paste it into Claude Code, Codex, Cursor or any agent with a terminal. Change the task to whatever you need.

prompt
Read https://acurast.dev/agents.md and follow it. Start a Small VPS on Acurast Canary for 2 hours with my SSH key at ~/.ssh/id_ed25519.pub. Show me the dry run and wait for my OK before deploying.

Or point it at the files

What the guide tells it

  • Asks before it spends

    Every deploy and payment waits for your OK, with network, size, duration and cost ceiling shown first.

  • Never sees the mnemonic

    It reads ACURAST_MNEMONIC from the environment and never prints, logs or commits it.

  • Canary first

    Free test tokens, real phones. Mainnet only when you say so.

  • Dry run, then deploy

    Every command runs with --dry-run first, and costs are capped per execution.

  • Cleans up

    Deployments it no longer needs are cancelled, which returns the unused tokens.

  • Machine-readable

    --non-interactive and --output json, so the CLI never stops to ask and the output parses.

The guide

Exactly what an agent gets from /agents.md.

agents.md
# Acurast for AI agents

Instructions for an AI agent that deploys and manages work on Acurast, a network of phones that run
code. Published by acurast.dev. Source of truth: https://docs.acurast.com (index for agents: https://docs.acurast.com/llms.txt).

## Rules

1. Ask your human before anything that spends funds: `acurast deploy`, `acurast deploy vps`, an x402 payment.
   Show them the network, the size, the duration and the cost ceiling first.
2. Never print, log, commit or send the mnemonic. Read it from the environment (`ACURAST_MNEMONIC`), not from chat.
3. Start on `canary`. Its cACU is free from https://faucet.acurast.com. Move to `mainnet` only when your human says so.
4. Run every deploy with `--dry-run` first, then without it.
5. Cap the cost: set `--max-cost-per-execution` (VPS) or `maxCostPerExecution` (acurast.json). Amounts are in
   the smallest ACU unit: 1 ACU = 10^12.
6. Cancel deployments you no longer need: `acurast cancel <deployment-id>` returns the unused locked funds.

## Set up

```sh
npm install -g @acurast/cli
acurast --version
```

Credentials go in `.env` (or the environment) in the working directory:

```sh
ACURAST_MNEMONIC="..."   # the deploying account; needs ACU on mainnet, cACU on canary
```

Optional: `ACURAST_IPFS_URL` and `ACURAST_IPFS_API_KEY` for your own IPFS gateway, and
`ACURAST_MAINNET_RPC` / `ACURAST_CANARY_RPC` to pick an RPC node. The CLI logs the RPC it used to
`.acurast/acurast.log`.

## Run a VPS (an SSH-able Ubuntu on a phone)

Non-interactive, machine-readable:

```sh
acurast deploy vps \
  --network canary \
  --min-memory 7GB \
  --min-storage 32GB \
  --authorized-ssh-key "$(cat ~/.ssh/id_ed25519.pub)" \
  --duration 24h \
  --non-interactive --output json --dry-run
```

Drop `--dry-run` to deploy. Other flags: `--min-compute-score <n>` (single-core benchmark),
`--min-cpu-multi-score <n>`, `--http-port <port>` (serve HTTP from the VPS on the same subdomain, port >= 1024),
`--callback-url <url>` (receives `log` / `started` / `error` events as JSON), `--exit-early`. Every flag has a
`VPS_*` environment variable (`VPS_MIN_MEMORY`, `VPS_DURATION`, ...); flags win.

The VPS is key-auth only. Connect through the Acurast tunnel:

```sh
ssh -o ProxyCommand='openssl s_client -quiet -servername %h -connect %h:443' root@<clientId>.acu.run
```

## Deploy your own code

```sh
npx @acurast/cli new my-app   # starter project
cd my-app && npm install && npm run bundle   # writes dist/bundle.js
acurast init                  # creates acurast.json and .env (or write acurast.json yourself)
acurast estimate-fee          # what the deployment will cost
acurast deploy --dry-run
acurast deploy
```

Code runs in Node.js on the phone. Globals: `print(msg)`, `httpGET(url, headers, ok, err)`,
`httpPOST(url, body, headers, ok, err)`, `environment(key)`, `_STD_.job.getId()`, `_STD_.device.getAddress()`,
`_STD_.job.storageDir`. Config reference: https://docs.acurast.com/developers/build/deployment-config/

## Manage deployments

```sh
acurast deployments ls            # all deployments of the account
acurast deployments <id>          # one deployment; ids look like Acurast:<address>:<number>
acurast deployments <id> -e       # push updated environment variables
acurast deployments --cleanup     # remove finished deployments
acurast cancel <id>               # stop it and get unused funds back
```

## No ACU? Pay in USDC

The Deploy Agent takes USDC on Base over x402: POST `https://deploy.acu.run/deploy` with
`{"script": "ipfs://..."}` or `{"vps": {"sshKey": "...", "maxExecutionTimeInMs": 7200000}}`. A request without
payment answers 402 with the price. Details: https://docs.acurast.com/developers/tools/deploy-agent/