Embed a Cast on Your Site or README
Generate a Markdown or HTML embed for an Atmos terminal recording, with a permanent, cacheable player URL that links back to atmos-pro.com.
A cast is a recording of a terminal session — an asciicast file (usually produced with a tool like
asciinema rec) checked into your repository. Atmos Pro can turn any .cast file in a public GitHub repository into a live, embeddable demo: a GIF for READMEs, or an interactive player for your site. Embedding a cast gives visitors a real, playable terminal demo with zero hosting of your own, and it links back to atmos-pro.com wherever it's embedded.Anonymous cast rendering only works for repositories that are public and already installed into an Atmos Pro
workspace via the GitHub App. If you get a
403 when trying to render a cast, the repository likely isn't installed
yet — see Import your repositories. It isn't a sign that the file path is wrong.- 1Locate your cast file. Any
.castfile path in a public, installed repository works. Try the Cast URL Builder to see the URL anatomy live against a real example. - 2Build the pretty URL. The shape is
https://atmos-pro.com/casts/{owner}/{repo}/{ref}/{path}. For{ref}you can use a branch name (main), a query-string ref (?ref=refs/heads/my-branch), or — recommended for anything you're embedding permanently — a commit SHA. - 3Copy the embed snippet. Use the Markdown form for GitHub READMEs, or the HTML form for a blog or docs site.
- 4Paste it. GitHub renders the Markdown image-link inline. Any site that allows iframes can use the HTML form for the full interactive player.
GitHub can't render an
<iframe> inside Markdown, so the README-friendly embed is an image link: the GIF artifact, wrapped in a link back to the interactive player page.[](https://atmos-pro.com/casts/acme/infra-live/a1b2c3d/demo.cast)For a site that supports iframes, embed the interactive player directly:
<iframe
src="https://atmos-pro.com/casts/acme/infra-live/a1b2c3d/demo.cast"
title="Atmos Cast"
width="960"
height="540"
style="border:0;max-width:100%;aspect-ratio:16/9"
allow="clipboard-write"
loading="lazy"
></iframe>If you already have a cast rendered, the fastest way to get both snippets is the Embed button on the cast's player page — it copies a snippet that's automatically pinned to the exact commit the cast was rendered from.
| URL form | Cache behavior | Best for |
|---|---|---|
Commit SHA (a1b2c3d) | Cached for a year, immutable — never re-renders | A permanent embed you don't want to silently change |
Branch or tag (main, ?ref=) | Re-resolves on a short TTL (a few minutes) | An embed that should track the latest recording |
If you embed a branch or tag URL, the recording shown will change whenever someone pushes a new
.cast file to that ref — pin to a SHA if you want the embed to stay exactly as it is today.A
403 means the repository isn't public or isn't installed yet. A 404 means the owner, repo, ref/SHA, or path is
wrong. A slow first load is normal — the artifact renders on first request and is cached after that; refresh after
10–30 seconds.Try the Cast URL Builder
Construct and validate a cast URL against a real example, and copy ready-to-use embed snippets.