Appearance
Your App VM
Some projects deploy to a full server instead of static files. This page explains how that server, your App VM, works: what runs there, what Stasho does on your behalf, and what you can check yourself.
Prerequisite: none, but Your data on-chain covers the encryption and verification model this page builds on.
Prompt for your agent
Copy this into Claude Code, Cursor or any agent that can run shell commands. Creating the VM runs in your browser; the agent guides you through it, then reads the VM's public status document.
text
Read https://docs.stasho.xyz/guides/your-app-vm.md. I am creating my App VM on Stasho. Walk
me through the Create App VM steps one at a time, in the page's words, and wait for me after
each step. The SSH key is mine: tell me how to print my public key, never generate or ask for
a private one. Never ask for the VM key, my wallet key or an SSH session. When I paste the
IPv6 host from the App VM home (it comes with square brackets), verify it: fetch
https://<ipv6 host>:8443/ (the certificate is self-issued) and read me each app's state.The model in one paragraph
Your App VM is one machine that Stasho creates, runs and pays for on your behalf, on a confidential host: its disk is encrypted and only unlocked once the host proves it runs the expected image, which protects it from the node operator. Each server app you deploy to it runs in its own container, watched over by the supervisor: a small always-on program that installs each server app, restarts it if it crashes, and reports its state back to the dashboard. Your usage stats (live CPU and memory per server app) are encrypted to your wallet's key before they leave the VM. You pay nothing for it. On the free trial, the VM runs for 14 days and is then deleted with its files, with no grace period.
What's public, what's encrypted
| Public by protocol | Encrypted |
|---|---|
| IPv6 address, and the IPv4 host and port used for SSH (a NAT mapping) | Your project names |
| Allocation: vCPU, RAM, disk | Your usage stats: live CPU and memory per server app |
| Default subdomain (by default a slug of the project's name) and custom domains | |
| VM image version and supervisor version | |
| SSH public keys and fingerprints | |
| Each server app's project ID and the hash of the bundle it runs |
The public column above is provisioning detail that's already visible to anyone who reads the underlying on-chain messages or asks the host running your VM directly; none of it is a Stasho decision to disclose, and deleting the VM doesn't retroactively hide what was public while it ran. What stays encrypted is exactly what would otherwise leak your project identity or activity: the project's own name, and how hard it's actually working. See Your data on-chain for the same split applied to projects and deployments.
How code reaches the VM
Stasho holds the keys that unlock your VM and vouch for its supervisor, so you trust Stasho with it. Its memory and disks are encrypted, which protects your VM from the node operator who runs the physical host.
Code reaches the VM by exactly one path: the supervisor, running on the VM itself, pulls your bundle from the public network, checks it, and runs it. There is no push path from our backend, and no remote-exec channel into your VM.
You can check what the supervisor runs. Before it runs a single line of your code, it works through a chain of checks, and every one of them is either an on-chain fact or a cryptographic proof, never a claim from Stasho:
- Resolve your deployment's on-chain storage reference and fetch the encrypted bundle from the storage network.
- Hash the fetched bytes and compare them against the hash your deployment recorded on-chain. A mismatch is rejected before anything is decrypted.
- Decrypt the bundle using the VM's own private key, a key generated on the VM at first boot and never sent anywhere. A wrong key or tampered ciphertext fails this step outright.
- Validate the unpacked manifest, including a check that the app was built for the exact Node.js major version the VM runs.
- Re-hash the unpacked application code against the hash recorded inside the bundle itself.
- Only after every step above passes does the supervisor start your app's container.
This is the same verify-what-runs principle described in Your data on-chain, applied to a running server instead of a static file. The exact wire format each step checks against is documented in the storage schema.
Filesystem layout
The supervisor and your server apps use a fixed set of paths on the VM, all on its encrypted state disk:
| Path | What's there |
|---|---|
/var/lib/stasho/vm-key | The VM's own private key, generated the first time it boots. Never leaves the VM. |
/var/lib/stasho/state.json | The supervisor's own record of what it has already applied: assigned ports, deployed bundles, its own version. |
/var/lib/stasho/agent/ | A copy of the current supervisor release, kept so an update to the VM image does not roll the supervisor back. |
/var/lib/stasho/caddy/ | The HTTPS certificates for your apps' domains. |
/srv/stasho/apps/<projectId>/<deploymentId>/ | Your unpacked application code, one directory per deployment, mounted read-only into the container. The supervisor keeps the newest 3 per project and removes older ones. |
/srv/stasho/apps/<projectId>/data/ | Your app's /data (see What your app can write). |
Each server app runs as the container stasho-app-<projectId>.
Everyday operations
SSH into your VM with one of the keys on the Access card of the App VM page (you added them when you created it, and you can change them), and use podman to inspect your app:
Watch a project's logs live:
bash
podman logs -f stasho-app-<projectId>Check whether it's currently running:
bash
podman ps --filter name=stasho-app-<projectId>The supervisor owns these containers
The supervisor starts stasho-app-<projectId> fresh on every deploy. Anything you change by hand is gone the next time you push. Treat SSH access as a window for inspection and debugging, not a place to configure your app permanently: changes belong in your repo.
SSH keys
The Access card on the App VM page lists the SSH keys that can log in to your VM, each by type and fingerprint.
- Add a key: paste one public key line and save. The VM accepts
ssh-ed25519,ssh-rsaandecdsa-sha2-nistp256keys. Other types, such asecdsa-sha2-nistp384or the hardware-key types that start withsk-, are refused. A key's comment can contain spaces. - Remove a key: use the remove action on its row. The last key has no remove action: a VM always keeps at least one key.
- Limit: a VM has at most 8 keys.
A confirmation lists the fingerprints being added and removed, and the change is saved at once. It takes effect at the VM's next restart. Until then the running VM keeps its previous keys: a new key cannot log in yet, and a removed key still works. The page marks both ("Added, applies at the next restart" and "Removed, still works until the next restart"). Restart the VM when you want the change to apply.
You can save up to 10 key changes an hour. Each saved change sends an email, to the address on the VM if it has one, listing the fingerprints added and removed. If you did not make the change, remove the key, restart the VM and write to hello@stasho.xyz.
The dashboard's list is the one that counts. The VM's key file, /root/.ssh/authorized_keys, is replaced with that list every time the VM starts. A key you add by hand over SSH works until the next restart and is then gone. A key you remove by hand comes back if it is still in the dashboard's list.
Restarting your VM
Restart on the status card of the App VM page restarts the VM. After a key change, the Access card offers the same action as Restart VM. Your apps stop until it is back, usually a couple of minutes. Files in /data are kept. The page's status line shows "Restarting" with what it is doing, and returns to "Running" when the VM is back.
- A VM can be restarted once every 10 minutes.
- The restart is not available while the VM is being created, moved to a new host, updated or deleted. The page says why.
- If a restart does not bring the VM back, the page shows the VM's state. If the host cannot start the VM for 15 minutes, Stasho moves it to a new host, as it does for any VM whose host fails. The files in
/dataon the old VM are gone in that case: see When your VM moves.
Ports and the firewall
The VM's firewall denies all inbound traffic by default. Only these are open:
| Port | What it's for |
|---|---|
| 22 | SSH |
| 80, 443 | Your apps, served over HTTPS on their default subdomains and custom domains |
| 8443 | The public status endpoint (below) |
Your apps listen on the VM's loopback interface only; a reverse proxy on the VM serves them on 80 and 443 for their domains, so an app's own port is never reachable from outside. The firewall also accepts ICMPv6, which is what makes IPv6 itself work.
The VM key
At first boot, the VM generates its own private key at /var/lib/stasho/vm-key and never sends it anywhere. It exists purely so the VM can decrypt bundles addressed to it.
Never copy this key off the VM, and never share it. Losing the VM (a move to a new host, a delete) is not the same as losing your deployments: every bundle you deploy is also encrypted to a key derived from your own wallet, so you can recover your deployment history and app code with your wallet's key while your wallet has credits, even if the VM that ran it is long gone. See Recover your data.
What your app can write
Your server app runs as a Next.js app (standalone output) on one Node runtime. It can write to two places, and everything else on the VM is read-only:
/data(also available asprocess.env.DATA_DIR). Files here are kept on this VM across restarts and updates: a redeploy replaces the app container, not/data. It is not backed up and it does not move with the VM. When the VM is replaced or re-created, the files in/dataare gone./tmp. It is memory-backed and cleared on every restart.
Keep durable data in a hosted database, not in /data. Treat /data as a local cache or scratch space that you can afford to lose.
When your VM moves
If the host your VM runs on stops responding, Stasho replaces the VM on a new host and redeploys your apps there. The timeline from a real replacement:
- A watchdog waits 15 minutes 30 seconds to confirm the host is really down.
- The VM then shows as moving to a new host. The replacement takes about 5 minutes to come up and be endorsed.
- Your apps are back about 10 minutes after the move starts, which is about 26 minutes after the host stopped.
Until the automatic redeploy lands, an app whose last bundle cannot be opened on the fresh VM reads "Waiting for redeploy". The old VM's /data is gone, so anything your app kept there has to be rebuilt or reloaded from your database.
You get one of two emails, sent to the address you gave when you created the VM, or to your sign-in email:
- "Your App VM moved to a new host" is sent when the replacement is up and your apps are redeployed.
- "Your App VM is down" is sent when a replacement failed after several attempts. The App VM home then offers "Create a new VM".
The status card on the App VM home shows the same states: running on a confidential host, moving to a new host (about 10 minutes), could not move after several attempts, and deleting. It also says when Stasho could not unlock your VM's disk.
When Stasho reinstalls your VM for a security rotation
If one of Stasho's signing keys has to be replaced, Stasho reinstalls your App VM on its host from a new image. If your account has an email address, you get an email, "Your App VM was reinstalled for a security rotation", when the VM is back.
- What stays: the VM's address, and everything your apps keep under
/data. - Your apps are offline from the reinstall until they are redeployed. Apps connected to GitHub are redeployed from the latest commit of their connected branch. An app without a GitHub connection stays offline until you deploy it again.
- Earlier deployments can no longer be rolled back to.
- Files on the VM outside
/dataare removed: container volumes, caches, files you placed over SSH. - The VM's SSH host key is new, so your SSH client warns once.
- TLS certificates are reissued. There is nothing for you to do.
Environment variables
Your project's environment variables travel inside the encrypted bundle itself, the same one the supervisor verifies and decrypts before running your app. There's no separate channel for them, and no way to change a running app's environment without redeploying: rotating a variable means redeploying. The next deploy bakes the new values into a new bundle, and the supervisor replaces the running container with one built from it.
Updates
Two different things update independently, on different schedules:
- The supervisor updates itself in place. It checks a signed, on-chain registry, and when a genuinely newer, hash-verified release is available, it swaps itself in and restarts, without disturbing your running server apps.
- The VM image (the OS, Node.js, the firewall rules) is updated in place by Stasho. The VM restarts once and your server apps are unreachable for a few minutes; the VM keeps its address, your data in
/dataand your apps. If your account has an email address, you get an email before the restart. A new VM, or a VM moved to a new host, starts from the latest image.
Update history and proofs
Each time the supervisor, its runtime, the app runtime or the VM image changes, your VM asks its AMD processor for a signed report that names exactly what it now runs, and posts that report publicly. Stasho checks every report and records them in batches on Solana. The Updates card on your App VM page lists them, newest first. Each row opens a public page, no sign-in needed, that checks the evidence for that update.
Four of the page's checks run in your own browser, on data it reads from Aleph and Solana directly, not from Stasho:
- The release was authorized. The registry message that lists the release is signed by a Stasho registry key (held on a Ledger device) that was valid at the time.
- The report commits to this update. The AMD report carries a fingerprint of the claim that names your VM and each updated part.
- The report is in a published batch. The batch's list of reports is on Aleph, posted by a published Stasho key, and holds this report.
- The batch is anchored on Solana. A Solana memo, paid for by a published Stasho key, names that list.
One check is Stasho's, and the page labels it so: AMD's signature on the report, the VM's launch policy, its firmware versions and the measurement of its boot image. To re-check that part yourself, the page offers a bundle with the report, AMD's certificates and step-by-step commands that use open tools and do not depend on Stasho's page.
What this does and does not show:
- The report covers the VM's boot image, not its disks, and Stasho holds the keys that unlock your VM's disks (see the model). The proof is about the host and the network, not about Stasho.
- The expected measurement of the boot image is not published in a signed record, so comparing it rests on Stasho.
- If one of Stasho's keys were stolen: with the Solana key alone, a thief could make a batch look up to five minutes older, nothing else. With the key that posts the batch lists alone, nothing. With both, a thief could forge a batch. A retired Solana key is refused by Solana's own clock. Retiring a leaked posting key does not stop it, because it writes its own dates, so when that key leaks Stasho retires the Solana key with it.
- The page reads Solana through a public RPC and takes the memo and its time on that RPC's word. You can enter an RPC of your own on the page.
- That free public RPC keeps only recent history, a day or two. For an older update the page says that the RPC does not have the update's Solana anchor and does not confirm it. To check such an update, enter an RPC of your own that keeps full history, or use the bundle, whose commands read Solana's own public endpoint.
The list starts at your VM's first report. A VM whose supervisor is older than 0.10.0 sends none yet.
Crashes
If your app keeps crashing, its container is restarted automatically, up to a point. Past that point, your deployment card in the dashboard shows:
App crashed on your App VM after N restarts. Check logs over SSH.
That message is deliberately generic. We don't ship your logs anywhere; they stay on the VM. SSH in and run podman logs -f stasho-app-<projectId> (see Everyday operations, above) to see what actually happened.
When your VM will not start
Creating an App VM takes about 6 minutes, and the App VM page shows each stage while it runs. If a stage fails, the page says "We could not prepare your VM." with one sentence naming the stage. When the failure happened before the VM existed, Try again reopens the setup with your SSH keys filled in; otherwise Delete clears it so you can create a new one. If preparing runs past 20 minutes, the page offers to delete the VM and start over.
The status endpoint
Port 8443 on your VM serves a small, public JSON document, no authentication, by design: it's what our health checks read, and anyone else can read it too. It exposes exactly:
- The supervisor's own version, and a hash identifying this VM
- For each deployed server app: its project ID, the hash of the bundle it's running, its current state (downloading, verifying, starting, serving, crashed, or verify-failed, which means the last bundle cannot be opened on this VM and a redeploy is on its way), its restart count, and its port
- An encrypted blob of that server app's live CPU and memory use, sealed to your wallet's encryption key. The endpoint carries only the ciphertext; it never sees, and never serves, the plaintext numbers.
It never exposes environment variables, keys, logs, file paths, project names, or anything else about your account beyond what's already public on-chain. The dashboard's App VM home decrypts the stats blob in your browser to show live CPU and memory; if your encryption key is locked, it shows "Unlock to view stats" instead.
Deleting your VM
Delete App VM on the App VM home removes the VM for good: every server app on it stops, its address is gone, and the files in /data and /tmp go with it. A new App VM gets a different address. Your deployments stay on-chain: when you create a new VM, Stasho redeploys your server apps on it once it comes up (on a free trial, deleting a running VM ends the trial).
Free trial
Any wallet can start one App VM as a free 14-day trial. A wallet we enabled by hand is not on the trial.
- How long. 14 days from when the VM first comes up. We email you on day 12, and again once it is gone.
- What ends. On day 14 the VM is deleted with everything on it,
/dataincluded. There is no grace period and no backup. Your deployed bundles stay recoverable while your wallet has credits; files your app wrote do not. - What it needs. A personal GitHub account connected (an organization install can't start one, and this replaces any organization install on the wallet, since there is one install per wallet; reconnect the organization afterwards if its projects need it), an email address, and the 14-day checkbox on the last step.
- One per wallet, one per GitHub account. Deleting a running VM ends your trial. Deleting one that failed to come up does not, so you can try again.
- How many. 8 a day and 100 a month across all wallets, resetting at 00:00 UTC. These are operational values and can change. When they run out,
/vmreads "Today's free trials are taken. More open at 00:00 UTC." or the same for the month.
Working with an agent
An agent cannot create an App VM for you: the three-step setup runs in your browser, and the server apps that run on the VM arrive through a repo import, which is yours too. An agent key with read and deploy can list an App VM app, read it and redeploy it, and a key that signs for itself (My agent signs) can also roll it back, attach and detach its custom domains, and delete the project (the VM stays), but no key creates one or changes its settings. A key tied to this one project can carry that signer. What an agent can do beyond that is read: the status document below is public, and an agent whose public key is on the VM's Access card can SSH in as root and read logs with podman like you would. No agent key changes the SSH keys or restarts the VM: that needs you signed in to the dashboard.
Any wallet can start one free trial. If /vm reads "App VMs are not enabled for this wallet", the setup cannot start: ask for access at hello@stasho.xyz first.
What the agent hands you, in these words:
text
In the Stasho dashboard open App VM in the sidebar. If there is no App VM entry, or the page
says trials are taken or already used, stop and read me its words. On a free trial, the VM and
its files are deleted on day 14. Step 1, What runs here: read it, tick the
acknowledgement, Continue. Step 2, SSH keys: paste the public key(s) that should open the
VM (print yours with `cat ~/.ssh/id_ed25519.pub`), Continue. Step 3, Email: optional, except
on a free trial, where it is required and you also tick the 14-day evaluation checkbox (a
"Connect your personal GitHub account" step may come first). Click Create. The page shows each
stage for about 6 minutes. When the status card reads Running, copy the IPv6 host value from
the Access card (it comes with square brackets) and paste it to me.How the agent verifies it afterwards. The VM's status document is public by design, so the check needs no account:
bash
curl -sk "https://$VM_HOST:8443/"VM_HOST is the bracketed value as copied, for example [2001:db8::1]; wrap a bare address in brackets yourself. -k is needed because the certificate is self-issued. The document carries agentVersion, instanceHash and apps: one entry per server app with its projectId, bundleHash, state (downloading, verifying, starting, serving, crashed or verify-failed), restarts and port. It also carries templateVersion (the VM image version, null on images older than 1.4.0) and hostNode (the Node.js version the supervisor runs on), as reported by the supervisor. A fresh VM answers with an empty apps list; after a server app's first deploy its entry reads serving. A connection refused or timed out means the VM is not up yet, or the address was mistyped. A 429 means the endpoint's limit of 300 requests a minute is spent: retry in a minute. "Network is unreachable" means the machine running the check has no IPv6. The IPv6 address can change if the host's address pool changes, so use it for checks like this one, not as a DNS target: a domain points at its CNAME (App VM records).
Related
- Your data on-chain: the encryption and verification model this page builds on
- Recover your data: recovering an app bundle with only your wallet key
- Storage schema: the exact wire format, including the bundle envelope