Skip to content

How to set up an xlm.sh site ​

Three steps:

  1. Have a Soroban Domain
  2. Upload your site to IPFS
  3. Point your Stellar account at the site

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.xlm are 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 on example.xlm.sh.
  • Client-side routing that needs every path to return index.html does 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.

Record type

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.