asciinema-server: self-hosting terminal session recordings and live streams

What asciinema-server actually hosts

The project is the server-side half of the asciinema ecosystem. The asciinema CLI records a terminal session into the asciicast format; asciinema-server stores those recordings, serves a web interface for browsing and managing them, and exposes an HTTP API that the CLI talks to. The README describes it as implementing "a hosting platform for terminal session recordings and live streaming" and points at the HTTP API as the interface used by the CLI.

The intended audience is narrow and specific. The README names the cases directly: people who are not comfortable hosting their data at asciinema.org, companies whose policy prevents it, and anyone who prefers to self-host. If you are a solo developer who just wants a link to a recording, the public instance already does that and the README says asciinema.org provides free hosting available to everyone. Self-hosting becomes interesting when the recording contains something you cannot put on a third-party service: internal hostnames, credentials in a prompt, customer data scrolling past.

Elixir, Phoenix, and an embedded virtual terminal

The stack is Elixir on the Phoenix framework, with PostgreSQL as the datastore. What separates this from a generic file host is the embedded virtual terminal, avt. The README states that avt is utilized for preview generation, recording analysis, and live stream state bookkeeping. In other words, the server does not merely store a blob and hand it to a browser. It replays the recorded byte stream through a terminal emulator on the server side, which is what makes preview images, content analysis, and live stream state possible.

That design decision has a cost. The repository carries a native/ directory and the Dockerfile builds Rust code before it ever touches Elixir: it copies native/, runs cargo build -r, and only then fetches mix dependencies. The justfile shows the same split, with format touching native/vt, native/fts and native/svg_raster alongside mix format. So a working build needs Elixir, Erlang, Node.js and a Rust toolchain, not just one language runtime. The README confirms this, listing Elixir 1.19 or later, Erlang/OTP 28 or later, Node.js, and the Rust toolchain used for the native NIFs.

The feature list follows from that architecture. Full-text search covers recording titles, descriptions, and, in the README's phrasing, "full terminal session content", because the server can read the session itself rather than only its metadata. Preview images are SVG, which the runtime image supports by installing rsvg-convert and a DejaVu font. Plain text transcripts can be downloaded as .txt. Recordings and streams carry a visibility setting of private, unlisted, or public, and sharing can be done through secret links.

Installing asciinema-server with the Nix dev shell

For local development the README recommends the Nix dev shell, which it says provides Elixir, Node.js, Rust and supporting tools. Clone the repository and enter the shell first:

git clone https://github.com/asciinema/asciinema-server
cd asciinema-server
nix develop

Inside that shell, mix setup installs dependencies, prepares the database and builds assets. The README names the three commands. A running PostgreSQL server is required either way, and the README states this separately from the toolchain, so the dev shell does not remove that dependency.

mix setup
just serve
mix test

The justfile defines serve as iex -S mix phx.server, so just serve and iex -S mix phx.server are the same thing; the README mentions both. mix test runs the suite. If you do not use Nix, you install Elixir 1.19 or later, Erlang/OTP 28 or later, Node.js and the Rust toolchain yourself, and the README does not list a package-manager recipe for any of them.

For a container deployment, the repository ships a Dockerfile that builds a release rather than running mix in production. It uses a hexpm/elixir builder image on Alpine, builds the Rust NIFs, runs mix release, and copies the result into a plain Alpine runtime image. The published defaults are worth reading before you override them:

ENV PORT=4000 \
    ADMIN_BIND_ALL=1 \
    DATABASE_URL=postgresql://postgres@postgres/postgres \
    RSVG_FONT_FAMILY="Dejavu Sans Mono" \
    PATH=/opt/app/bin:${PATH}
ENTRYPOINT ["/sbin/tini", "--"]
CMD ["/opt/app/bin/server"]
EXPOSE 4000

The container listens on port 4000 and expects PostgreSQL at the host named postgres with user postgres and database postgres. That default is a development convenience, not a production configuration: the password is absent and the hostname assumes a Compose or Kubernetes service named postgres. The runtime image also installs fd, rsvg-convert, ttf-dejavu, pngquant and tzdata, which is a hint that preview rendering and timezone handling happen inside the container rather than at request time in the browser.

The build weight is the real adoption cost

The most honest limitation is visible in the Dockerfile before you run anything. The builder stage installs nodejs, npm, rust, cargo and build-base, builds the Rust code, fetches and compiles prod dependencies, installs npm packages, runs mix assets.deploy, and then runs mix release. The file even carries a comment about avoiding "error 137" (out of memory) while building images, which is the kind of note that exists because someone hit it. Building this image needs more memory and time than a typical Phoenix application.

The second limitation is that the README does not document rollback. It covers development, the feature list, and the self-hosting pointer, but says nothing about how to revert a release, how database migrations behave across versions, or what happens to existing asciicast data when the schema changes. If you plan to upgrade a production instance, that gap is where you should spend your own investigation time, starting with the self-hosting documentation rather than the README.

The third case is a mismatch of purpose. asciinema-server stores terminal sessions in asciicast, not video. If you need to record a desktop, a browser, or a graphical application, this is the wrong tool and the README makes no claim otherwise. It is also the wrong tool if you only want to hand someone a single recording: the public instance, or a static asciicast file served from any web host with the asciinema player, covers that without PostgreSQL, Rust, or an Elixir release. The server earns its keep when you need accounts, visibility control, search, and an API that the CLI can push to.

How it differs from a general-purpose artifact store

The obvious alternative is not another terminal recorder but a generic storage and sharing layer: object storage plus a static site, or a file-sharing service with a player embedded. The difference in approach is where the terminal emulation runs. A generic store treats the recording as an opaque file. It can serve bytes and it can serve a thumbnail you generated yourself, but it cannot tell you what was on screen at second forty of the session, because nothing in the pipeline understands the format.

asciinema-server inverts that. Because avt is embedded, the server can generate preview SVG images, produce plain text transcripts, analyze the session, and track live stream state. That is why full-text search can cover session content rather than just titles and descriptions, and it is a capability you cannot bolt onto object storage without writing your own asciicast parser and terminal emulator. The trade is operational: you are running a PostgreSQL-backed Phoenix release with native extensions instead of a bucket. For a small number of recordings, the bucket wins on effort. For a team that records sessions regularly and needs to find them again, the embedded terminal is the whole point.

Licence, maintenance and upgrade cost

The code is licensed under the Apache License, Version 2.0, and the README points at the LICENSE file for details. Apache-2.0 is a permissive licence with an explicit patent grant and a requirement to preserve notices; it does not impose copyleft obligations on your own code. This is a description of the licence text, not legal advice, and if you plan to redistribute a modified server you should read the LICENSE file and the NOTICE handling yourself.

On maintenance, the repository is not archived and the last push was on 2026-08-14. The recent release tags v20260626, v20260616 and v20260207 use date-based version strings, which tells you the project cuts releases on its own schedule rather than following semantic versioning. There is no documented long-term support branch, and the README does not describe an upgrade path between releases, so treat each version bump as something to test against a copy of your database. The repository includes a CONTRIBUTING.md and a .github directory, and the README asks contributors to read the contribution guidelines before proposing changes. The project also states that its sustainability relies on donations and sponsorships, with Brightbox listed as a sponsor, and offers paid consulting for hosting, maintenance and customization. That is a relevant fact when you weigh how much internal Elixir and Rust expertise you would need to carry the server yourself.

Editorial conclusion

Adopt asciinema-server if you already record terminal sessions with the asciinema CLI and need the recordings to stay inside your own network, or if full-text search across session content matters to you. Do not adopt it as a general screen-recording service, and do not adopt it if you cannot run PostgreSQL and an Elixir release. Before committing, verify the exact environment variables your deployment needs against the documented self-hosting guide, and confirm that your PostgreSQL instance is reachable from the container at the DATABASE_URL you set.

Frequently asked questions

Official sources

1. asciinema/asciinema-server on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases