asciinema-server: Self-Hosting the Backend for asciicast Recordings
Platform for hosting and sharing terminal session recordings
At a glance
- What is it?
- The asciinema server is the Elixir and Phoenix half of the asciinema ecosystem, storing asciicast recordings, indexing their terminal output for search, and relaying live streams. It is a reasonable fit for teams that already record with the asciinema CLI and cannot or will not host those recordings on asciinema.org.
- Who is it for?
- Adopt asciinema-server if your recordings are already produced by the asciinema CLI and your constraint is where they live, not how they are captured. Do not adopt it as a general screen recording platform, and do not expect a single-container deployment: the README requires PostgreSQL, Elixir 1.19 or later, Erlang/OTP 28 or later, Node.js and a Rust toolchain for the native NIFs.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 33 days ago.
- What is it written in?
- Mainly Elixir, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap asciinema-server fills between the CLI and a public host
The asciinema CLI produces asciicast files. Those files are small, text-based, and useless to a colleague unless there is somewhere to put them. asciinema.org is that somewhere for most people, and the README describes it as a public instance managed by the asciinema project team offering free hosting for recordings and streams. The server repository is the software behind that instance, published so it can be run elsewhere.
The stated audience is narrow and explicit. The README names three cases: you are not comfortable hosting your data at asciinema.org, your company policy prevents it, or you simply prefer self-hosting. That is a hosting decision, not a feature decision. If none of those three applies, the public instance already runs this same code and you gain little by operating a second copy.
What you get by running it yourself is control over the storage layer and the access rules, plus the ability to point the CLI at an internal hostname. What you take on is the operational surface of a Phoenix application: a database, an asset build, a native extension, and release upgrades on the project's own version cadence.
avt, full-text search over terminal output, and what the server actually computes
The mechanism worth understanding is the embedded virtual terminal. The README states that the server embeds asciinema's virtual terminal, avt, and that avt is used for preview generation, recording analysis, and live stream state bookkeeping. A recording is not a video and not a screenshot sequence. It is a stream of terminal escape sequences, and to produce an SVG preview image or to know what a live stream currently looks like, something has to interpret those sequences the way a terminal emulator would. That is avt's job, and it is written in Rust, which is why the development requirements include the Rust toolchain for native NIFs.
This design has a visible consequence in the feature list. The README claims full-text search using recording titles, descriptions, and full terminal session content. Searching terminal content is only possible because the server has already replayed the session through avt and captured the resulting text. A server that merely stored asciicast files and served them back could not offer that search without doing the same work at query time.
The same virtual terminal underpins live streaming. Keeping a stream's state means continuously feeding output through avt as it arrives, rather than only at upload. That is a heavier runtime shape than a file host, and it explains why the server is an application with a database rather than a static bucket with an index.
Metadata is editable after the fact: title and long description in Markdown. Visibility is per recording and per stream, with private, unlisted, and public as the three settings. Sharing is done through secret links, and embedding is offered either as the player itself or as a linked SVG preview image.
Getting it running: Nix dev shell, mix setup, and the PostgreSQL requirement
The README gives a short path. Clone the repository, then either enter the Nix dev shell or install the toolchain yourself.
git clone https://github.com/asciinema/asciinema-server cd asciinema-server nix develop
The README calls the Nix dev shell the recommended way and says it provides Elixir, Node.js, Rust, and supporting tools. If you skip Nix, the stated versions are Elixir 1.19 or later, Erlang/OTP 28 or later, Node.js, and the Rust toolchain. Either way, the README is unambiguous that a running PostgreSQL server is required. There is no SQLite fallback mentioned.
With dependencies in place, the workflow is three commands:
mix setup just serve mix test
The README describes mix setup as installing dependencies, setting up the database, and building assets. just serve starts the server, and the README notes that iex -S mix phx.server is the equivalent if you prefer an interactive shell. mix test runs the test suite.
That is the whole documented bootstrap. The README does not list environment variable names, database URL formats, or secret key configuration in the material available here, so treat the self-hosting page in the docs as the source for those rather than guessing at config keys. The default branch is develop, which is worth noting if you clone without specifying a branch and then wonder why the code does not match a tagged release.
Where the setup cost is real: native code, database, and release cadence
The Rust dependency is the first place a deployment can go wrong. Native NIFs are compiled artifacts, and they tie a built release to a specific architecture and to a compatible Erlang runtime. A build that works on an x86_64 Linux CI runner is not automatically portable to an ARM host or to a different libc. The README presents the Rust toolchain as a plain requirement rather than explaining the failure modes, but the requirement itself is the signal: this is not a pure Elixir application you can ship as a single BEAM file.
PostgreSQL is mandatory and is a second moving part. The README does not describe a migration or backup story in the material available, so the operational burden of schema upgrades across releases is something you would need to confirm from the docs before committing to a production instance.
The release cadence shown in the repository metadata is frequent. Three tagged releases appear within roughly seven months, v20260207, v20260616, and v20260626, with the last two only ten days apart. Frequent releases are not inherently a problem, but they mean upgrade work recurs. If you pin a version and stop, you accumulate divergence from a project that is clearly still moving.
Finally, this is the wrong tool if your recordings are not asciicast. The server hosts asciicast format recordings and streams them. It is not a general video platform, not a screen recorder, and not a place to drop MP4 files. The capture step happens in the CLI, and the server assumes that has already occurred.
asciinema.org versus a self-hosted instance: the same software, different trade-offs
The most direct alternative is asciinema.org, and the comparison is unusual because it is not a competing implementation. The README states that asciinema.org is a public asciinema server instance managed by the asciinema project team. Running the server yourself means running the same application with a different operator.
The difference is therefore entirely in the operational and policy layer. On asciinema.org, someone else holds the database, applies the upgrades, and absorbs the native build complexity. Recordings live on infrastructure you do not control, which is precisely the objection the README anticipates. Self-hosting moves the data inside your network boundary and moves every one of those operational tasks onto your team.
A second alternative is to skip hosting entirely and treat asciicast files as build artifacts: commit them to a repository, attach them to tickets, or serve them from static storage. That approach keeps the files but loses everything the server computes. No SVG previews, no search across terminal content, no live stream state, no per-recording visibility settings. Whether that loss matters depends on whether anyone actually browses your recordings later or whether they are consumed once and forgotten.
The server's own feature list is the honest test here. If you need secret-link sharing, three-level visibility, Markdown descriptions, and search over terminal output, the static-file approach will not substitute. If you need a place to park a file and link to it, it will.
Licence, donations, and the maintenance economics
The code is licensed under the Apache License, Version 2.0, per the README and the repository metadata. Apache-2.0 is a permissive licence that permits commercial use and modification and includes an explicit patent grant. It does not, as far as this material shows, come with any warranty or support commitment. If you modify the server for internal use, the licence does not oblige you to publish those changes. This is a description of the licence text, not legal advice; read LICENSE and consult counsel if the distinction matters to your organisation.
The README is candid that sustainability depends on donations and sponsorships, and it lists Brightbox as a sponsor. It also points to paid consulting services for hosting, maintenance, and customization of the server. Read together, those two paragraphs describe a project with a funded maintainer path but without a commercial support contract bundled into the open source licence. If you need a guaranteed response time, the consulting page is the route the project itself offers.
The practical maintenance cost is the sum of the parts already described: PostgreSQL operations, a Rust native build in your pipeline, asset building with Node.js, and periodic Elixir and Phoenix upgrades to keep pace with a release stream that has produced three tags in about seven months. None of that is unusual for a Phoenix application, but it is a real recurring cost and it is the reason the hosting decision and the operating decision should be made together rather than separately.
What to verify before you commit to running it
Check that your PostgreSQL instance is reachable from wherever the application will run, because the README treats it as a precondition rather than an option. Then confirm that the Rust toolchain produces the avt NIF on your actual target architecture, not just on a developer laptop, since that is the dependency most likely to differ between environments. Confirm which branch or tag you are deploying, given that develop is the default branch.
The feature set is documented well enough to decide on: asciicast hosting, live streaming, the embedded player, full-text search including terminal content, secret-link sharing, SVG preview embedding, three visibility levels, Markdown metadata, configurable themes and fonts, and plain text transcript downloads. The privacy claim is stated plainly as no tracking and no ads.
What the README does not give you is a deployment recipe. Environment variables, secret configuration, reverse proxy setup, and backup procedures are not in the material available here. Those live in the self-hosting documentation, and that page, not this repository's README, is what determines how long a first production deployment actually takes.
Editorial conclusion
Adopt asciinema-server if your recordings are already produced by the asciinema CLI and your constraint is where they live, not how they are captured. Do not adopt it as a general screen recording platform, and do not expect a single-container deployment: the README requires PostgreSQL, Elixir 1.19 or later, Erlang/OTP 28 or later, Node.js and a Rust toolchain for the native NIFs. Verify first that your PostgreSQL instance is reachable and that the Rust toolchain builds avt on your target architecture, because that native dependency is the part most likely to break on an unusual host.
Community notes