Recover Your Data

This guide walks you through reconstructing your full Aleph Cloud App project and deployment history using only your wallet's private key. The recovery script does not depend on our backend — it talks directly to the public Aleph network.

The standalone recovery script lives at scripts/recovery/ in the project repository. If you'd rather write your own tool in a different language, the Aleph Storage Schema is a complete, language-agnostic spec.

When to use this

• You no longer trust the platform and want to verify your data is portable
• The platform has gone away (bankrupt, compromised, taken down)
• You want to migrate your project history to a new tool
• You want to audit what data exists about your projects on Aleph

What you need

1. Your wallet's private key. Export it from MetaMask (Settings → Security → Show Private Key) or whatever wallet you use to sign in. The script never transmits this key anywhere; it only uses it locally to decrypt your data.
2. Node.js 22 or later. Verify with node --version.
3. The recovery script source. Clone the project repository and run it from scripts/recovery/.
4. Your wallet address. The 0x-prefixed Ethereum address you used to sign in.

Steps

1. Install the script

git clone https://github.com/cpascariello/aleph-cloud-app.git
cd aleph-cloud-app/scripts/recovery
npm install

2. Run it

The script reads your private key from the USER_PRIVATE_KEY environment variable. Never pass it as a CLI flag — it would leak into your shell history.

export USER_PRIVATE_KEY=0xYOUR_PRIVATE_KEY_HERE
npm run recover -- --address 0xYOUR_WALLET_ADDRESS --output ./my-recovery.json

You should see output like:

[recover] Wrote 3 projects, 21 deployments, 0 warnings to ./my-recovery.json

3. Inspect the output

Open my-recovery.json. You'll see a JSON document with:

• wallet — the address you recovered
• recoveredAt — timestamp of the recovery
• stats — counts of messages read, projects + deployments recovered
• projects — your full list of projects, each containing its own list of deployments
• warnings — any non-fatal issues encountered during recovery

Each project includes its name, source repo, branch, build configuration, and the full deployment history (with status, CID, URL, commit, error, etc.).

Schema v4 (May 2026 onwards): Each deployment POST references its artifact by storeRef (the STORE message's item_hash). The recovery script fetches each STORE to resolve storeRef → cid. If a project was deleted, the corresponding STORE has been FORGOTten and the script reports storeRef → null with a STORE_FORGOTTEN warning — the deployment metadata survives but the artifact CID is no longer recoverable.

4. Verify against the audit endpoint (optional)

If our backend is still running, you can compare your recovery output to what the backend claims:

curl https://api.stasho.xyz/api/audit/0xYOUR_WALLET_ADDRESS | jq

The backendView.cachedProjects and backendView.cachedDeployments should match your recovery output's stats.projectsRecovered and stats.deploymentsRecovered. Any discrepancy means either a bug or — in the worst case — backend dishonesty. The recovery script is the ground truth.

Troubleshooting

"private key derives to X, not Y" — Your private key doesn't match the address you supplied. Double-check both.

"Aleph API unreachable" — Try a different Aleph API endpoint with --aleph-api https://api2.aleph.im or similar.

Warnings about decryption failures — Some messages couldn't be decrypted. This usually means the encryption envelope is malformed or tampered with. The script skips these and continues, but the warnings tell you which messages had issues.

Empty output — Your wallet has no Aleph Cloud App data. Either you've never used the platform with this wallet, or the channel name is wrong (try --channel ALEPH-CLOUDAPP).

Warning codes

The recovery output includes a warnings array. The codes you might see:

Code	What it means
STORE_FORGOTTEN	A deployment's STORE was FORGOTten (project was deleted). Metadata is in the output but cid is null.
STORE_FETCH_FAILED	The Aleph node didn't respond when the script tried to resolve a storeRef. Try re-running.
LEGACY_SCHEMA	A deployment uses the pre-May-2026 schema (inline cid, no storeRef). The script handles it gracefully by reading cid directly.
ALEPH_MESSAGES_TRUNCATED	The Aleph API capped the response. Re-run with a date filter or paginate.

Independence

The script depends only on:

• Public Aleph HTTP API (any node — see https://aleph.im for the list)
• Standard cryptographic primitives (AES-256-GCM, ECIES-secp256k1)
• Node.js stdlib + two npm packages (eciesjs, ethers)

No part of this recovery flow depends on our infrastructure remaining online. If you have your private key and access to any Aleph node, you can recover your data forever.