# 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/