ascii.live: a Go server that turns a URL into an animated terminal stream

One URL, one animation, no client install

ascii.live is described as a project for hosting curl-based animations, all in one place, and a follow up to parrot.live.

The mechanism is deliberately minimal. You run a curl command against a path and the server writes an animation to standard output.

curl ascii.live/parrot

There is no client library, no plugin, no JavaScript and no account. The output is ANSI text, so whatever renders your terminal renders the animation, which is why the project calls itself curl-based. The topics are curl, gif and terminal, and the demo.gif in the repository root is there because an animation that only exists in a terminal needs to be shown in a README.

The audience is two overlapping groups. One is the person who wants an animation to put in a chat message, a conference slide or a terminal demo, and who wants a URL rather than a script to install. The other is the person who wants to contribute a new animation, and for that group the project is structured to be picked up in a few minutes.

What this is not is worth saying plainly. There is no authentication, no session state, no rate limiting described anywhere in the repository, and no account system. The service is a public HTTP endpoint that returns text. If you need something that a logged-in user sees, this is the wrong shape entirely.

Animations are Go files in a frames package

The contribution guide tells you exactly how to add an animation, and the shape of the code is the whole architecture.

You fork the repository, create a new frame file in the /frames directory named after your animation, for example parrot.go, and inside it you create an exported list of frames.

package frames

// This is the value stored in the FrameMap
var MyAnimation = DefaultFrameType(myAnimationFrames)

var myAnimationFrames = []string{
  `Frame1`,
  `Frame2`,
  `Frame3`,
}

Then you add your animation to the FrameMap in./frames/frames.go, commit, push and open a pull request.

Two things about this design are worth pointing out. First, an animation is just a slice of strings, and the frames are raw string literals with backticks, so a frame can contain escape sequences without escaping. That is what makes it possible to express a colour-cycling terminal animation in plain Go source with no asset files.

Second, the exported variable is wrapped in DefaultFrameType, and the comment says that this is the value stored in the FrameMap. So the type is what the map holds, and the type is presumably what carries the behaviour of playing the frames, such as the delay between them and how the sequence ends. The README does not define DefaultFrameType, so the details of playback live in the code rather than the documentation.

The frames directory is a Go package like any other, so the compiler checks that every contributed animation matches the type the map expects. A malformed contribution fails at build time rather than at request time, which is a better failure mode than the alternative.

The dependency set is two libraries old enough to notice

The go.mod file is short enough to read in full, and it is the most informative thing about the project's vintage.

module github.com/hugomd/ascii-live

go 1.17

require (
	github.com/golang/glog v0.0.0-20160126235308-23def4e6c14b
	github.com/gorilla/mux v1.7.3
)

Two dependencies. gorilla/mux is the HTTP router, which is the obvious choice for a server that maps a path like /parrot to a frame set. glog is the Google logging library, pinned to a 2016 commit.

The go directive says 1.17, and the Dockerfile builds with golang:1.17-alpine, so the project targets a Go release from 2021 and pins the compiler image to match. Nothing here is broken, but it is a project that has not moved its toolchain, which is worth knowing if you are planning to depend on it for anything long-lived.

The glog pin is a separate point. glog is a common transitive dependency, and pinning it to a specific 2016 commit rather than a version range is what you do to keep a build reproducible when a dependency's transitive graph is unstable. It also means the log output format is whatever glog was in 2016, which is fine for a server whose main job is writing bytes to a socket.

The dependency count is the interesting part. There is no template engine, no session store, no configuration library. The service does one thing, and the dependencies match that.

Running it: Hermit for the toolchain, a port 8080 server

The README documents two ways to run the server, and the local one starts with a detail that is worth copying.

The Go toolchain is managed by Hermit, and you activate the environment to automatically download and use the pinned Go version.

source bin/activate-hermit

That is why the repository has a bin/ directory. The alternative is managing a Go version yourself and hoping it matches what the project expects. The Hermit approach means the bin/ directory in the checkout carries the pinned toolchain and the activated environment uses it, so a contributor and a CI runner get the same compiler.

Then you run the server.

go run main.go

The server listens on port 8080. The README says to run the site in Docker as well, and the image is straightforward.

docker run -p 8080:8080 hugomd/ascii-live:latest

The Dockerfile is a two stage build that is worth a look because it is a good example of a minimal image. The build stage uses golang:1.17-alpine, installs ca-certificates, copies the source into the module path, downloads the modules, and builds a static binary with CGO_ENABLED=0 and GOOS=linux. The runtime stage is FROM scratch, copies in only the binary and the CA certificate bundle, and sets the command to the binary at the root of the image.

A scratch image with two files in it is about as small as a container gets, and it is a good fit for a service whose entire job is to write bytes. The ca-certificates copy is there so the server can make outbound TLS connections if it needs to, and it is the reason the build stage installs the package at all.

Where the animations actually come from

The frame contributions table is a short list of named people, their frame file, and the repository the animation came from.

The listed contributors are hexrcs with forrest.go from run-forrest-run, jmhobbs with parrot.go from terminal-parrot, and ahs3n with knot.go from torus-knot.

That table tells you the project is a collection rather than a set of originals. The frames are ports of animations that already existed as standalone projects, and the reference in each row is the upstream you would go to for the original.

The related projects list is the same story. parrot.live is the predecessor and shares an author, terminal-parrot and cultofthepartyparrot.com are both by jmhobbs, and parrotsay is by matheuss. So ascii.live sits in a family of terminal-parrot-like animations, and the value it adds over the originals is the single host: one domain, one curl command, no local installation, and a growing catalogue that does not require a separate URL per animation.

The upside of that model is obvious and the downside is worth naming. A catalogue assembled from ports is only as good as its newest contribution, and there is no sign in the README of any automated check beyond the Go compiler verifying that each frame file matches the type the map expects. The rendering itself, the frame delay, the escape sequences, whether an animation looks right in a given terminal, is not something a unit test would catch, which is why the pull request review is the actual quality gate here.

GPL-3.0 and no release tags

Two facts about the project's status are worth stating.

The licence is GPL-3.0, with the LICENSE file at the repository root. For a service that returns pre-rendered text, that licence mostly matters if you want to fork and run your own instance with your own frames, and there the copyleft obligation is the part to read before you publish a derivative. This is a description of what the licence file says rather than advice on how it applies to a particular deployment.

The second fact is that the repository has no GitHub releases. The last push was on 2026-10-12, so the code is being worked on, but there is no tagged artefact and no changelog in the repository listing. For a project whose deployment unit is a Docker image pulled with the latest tag, that absence is understandable. It does mean there is no way to pin a version of ascii.live, and that the published endpoint's behaviour can change without a version marker.

The repository layout is small: .github/, Dockerfile, LICENSE, README.md, bin/, demo.gif, deployment/, frames/, go.mod, go.sum and main.go. The deployment/ directory presumably holds the configuration for the hosted instance, and main.go is the entry point that wires the router to the frame map. Nothing here suggests a service with users, accounts, quotas or a persistence layer, which is consistent with the design and with what the README describes.

Editorial conclusion

ascii.live suits a developer who wants a single URL to paste into a terminal for an animation, or who wants to contribute a new one, because the contribution path is a Go file plus a map entry and a pull request, with no build tooling to learn. It is the wrong tool for anything involving a browser, a headless server that needs a login, or a workload, since the output is ANSI text and the server has no notion of sessions, authentication or content negotiation. Before you depend on the hosted endpoint, note that the project has no GitHub releases and the only published deployment is the Docker image hugomd/ascii-live:latest, so if you need a stable URL for a script, run the container yourself on the port 8080 the server listens on.

Frequently asked questions

Official sources

1. hugomd/ascii-live on GitHub
2. Issues
3. License: GPL-3.0
4. README