How to set up an xlm.sh site
Three steps:
Have a Soroban Domain
You need a domain such as example.xlm that:
- is in the original Soroban Domains registry v1 and has not expired (domains that exist only in Registry V2 are not served yet),
- is a top-level name (sub domains such as
blog.example.xlmare not served), - points to a Stellar account you control (an address starting with
G).
Domains are managed at app.sorobandomains.org. The form below checks your domain against these rules before building anything, so you can try it first.
Upload your site to IPFS
Your site must be a static site: HTML, CSS, JavaScript and other files in one folder, with an index.html at the top. Upload the whole folder to IPFS and note its CID.
You can run your own node with IPFS Desktop or Kubo (ipfs add -r --cid-version=1 ./site), or use a pinning service such as Filebase or Pinata, which upload and keep your files online for you.
Whichever you choose, keep the content pinned somewhere you control. xlm.sh pins sites that are visited, but that is a speed-up, not a hosting guarantee.
A few tips for sites served from IPFS:
- Use relative links (
./about.html) or links from the root (/about.html); both work onexample.xlm.sh. - Client-side routing that needs every path to return
index.htmldoes not work. Use hash routing (/#/about) or generate one HTML file per page. - Directories are served through their
index.html.
Point your Stellar account at the site
Enter your domain and your CID (or IPNS name) below. The form looks up the account your domain points to and builds a transaction that sets the account's app.xlm_sh.ipfs (or app.xlm_sh.ipns) data entry. You then sign it with that account on Refractor, which works with Freighter, Albedo, xBull, Ledger and other wallets and submits the transaction once it is signed. You can also copy the transaction into your own wallet instead. This page never sees your keys.
The account needs a little spare XLM: every data entry raises its minimum balance by 0.5 XLM (the base reserve), which you get back when the entry is removed. Replacing an existing xlm.sh entry costs nothing extra.
After the transaction is submitted, open https://<your-name>.xlm.sh. Changes can take a minute or two to show up because of caching. If you see an error page instead, Troubleshooting explains each one.
Your site must follow the acceptable use rules; sites that break them are blocked.
To publish a new version later, upload the new files and run the form again with the new CID. Or point the entry at an IPNS name or a DNSLink domain once, and update that instead; see Record specification.