Chainguard Container for asciinema

asciinema is a CLI tool for recording and sharing terminal sessions. It records terminal sessions as lightweight text-based recordings (casts) that can be played back, converted between formats, and shared.

Chainguard Containers are regularly-updated, secure-by-default container images.

Download this Container Image

For those with access, this container image is available on cgr.dev:

docker pull cgr.dev/ORGANIZATION/asciinema:latest

Be sure to replace the ORGANIZATION placeholder with the name used for your organization's private repository within the Chainguard Registry.

Compatibility Notes

The asciinema image is based on the upstream asciinema container image available at ghcr.io/asciinema/asciinema. This Chainguard image provides the same functionality as the upstream image with the following differences:

• Base OS: The upstream image uses debian:trixie-slim as its base, while this Chainguard image is built on Wolfi. This means apt and other Debian-specific tools are not available. If you need to install additional packages, use apk with the -dev variant.
• Minimal Design: This image includes only the asciinema binary and its essential runtime dependencies, significantly reducing the attack surface and CVE count compared to the Debian-based upstream.
• Non-Root User: The container runs as a non-root user by default, following security best practices.
• Regular Updates: The image receives daily automated builds to incorporate the latest security patches.

All asciinema commands and features work identically to the upstream image, including recording, playback, format conversion, and server authentication.

Getting Started

The asciinema image provides a command-line tool for recording and managing terminal sessions. The following examples demonstrate common usage patterns.

Recording a Terminal Session

To record a terminal session, you can run a command directly and save the output to a file:

docker run --rm -v $(pwd):/recordings cgr.dev/ORGANIZATION/asciinema record -c 'echo "Hello, asciinema!"' /recordings/demo.cast

This command records the execution of echo "Hello, asciinema!" and saves it to demo.cast in your current directory. The recording uses the default v3 format.

You can also specify the output format explicitly:

docker run --rm -v $(pwd):/recordings cgr.dev/ORGANIZATION/asciinema record --output-format asciicast-v2 -c 'ls -la' /recordings/demo.cast

Converting Between Formats

asciinema supports converting recordings between different formats:

docker run --rm -v $(pwd):/recordings cgr.dev/ORGANIZATION/asciinema convert /recordings/demo.cast /recordings/demo-v3.cast

This converts an older format recording to the latest v3 format. You can also convert to text or raw formats:

docker run --rm -v $(pwd):/recordings cgr.dev/ORGANIZATION/asciinema convert --output-format txt /recordings/demo.cast /recordings/demo.txt

Concatenating Recordings

To combine multiple recordings into a single file:

docker run --rm -v $(pwd):/recordings cgr.dev/ORGANIZATION/asciinema cat /recordings/demo1.cast /recordings/demo2.cast > combined.cast

Playing Recordings

While the container environment limits interactive playback capabilities, you can output recordings to standard output for further processing:

docker run --rm -v $(pwd):/recordings cgr.dev/ORGANIZATION/asciinema cat /recordings/demo.cast

Configuration

Authenticating with asciinema.org

To authenticate with asciinema.org for uploading recordings, you can use the auth command:

docker run --rm cgr.dev/ORGANIZATION/asciinema auth --server-url https://asciinema.org

This command generates an authentication URL that you can open in your browser to link your local CLI with your asciinema.org account.

Using a Custom Server

asciinema supports self-hosted servers. You can configure the server URL using the --server-url option:

docker run --rm cgr.dev/ORGANIZATION/asciinema auth --server-url https://asciinema.example.com

Environment Variables

The asciinema CLI respects the ASCIINEMA_SERVER_URL environment variable:

docker run --rm -e ASCIINEMA_SERVER_URL=https://asciinema.example.com cgr.dev/ORGANIZATION/asciinema auth

Documentation and Resources

For more information about asciinema's features and capabilities, refer to the following resources:

• asciinema Official Documentation
• asciinema GitHub Repository
• asciinema File Format Specification

What are Chainguard Containers?

Chainguard's free tier of Starter container images are built with Wolfi, our minimal Linux undistro.

All other Chainguard Containers are built with Chainguard OS, Chainguard's minimal Linux operating system designed to produce container images that meet the requirements of a more secure software supply chain.

The main features of Chainguard Containers include:

• Minimal design, without unnecessary software bloat
• Daily builds to ensure container images are up-to-date with available security patches
• High quality build-time SBOMs attesting to the provenance of all artifacts within the image
• Verifiable signatures provided by Sigstore
• Reproducible builds with Cosign and apko (read more about reproducibility)

For cases where you need container images with shells and package managers to build or debug, most Chainguard Containers come paired with a development, or -dev, variant.

In all other cases, including Chainguard Containers tagged as :latest or with a specific version number, the container images include only an open-source application and its runtime dependencies. These minimal container images typically do not contain a shell or package manager.

Although the -dev container image variants have similar security features as their more minimal versions, they include additional software that is typically not necessary in production environments. We recommend using multi-stage builds to copy artifacts from the -dev variant into a more minimal production image.

Need additional packages?

To improve security, Chainguard Containers include only essential dependencies. Need more packages? Chainguard customers can use Custom Assembly to add packages, either through the Console, chainctl, or API.

To use Custom Assembly in the Chainguard Console: navigate to the image you'd like to customize in your Organization's list of images, and click on the Customize image button at the top of the page.

Learn More

Refer to our Chainguard Containers documentation on Chainguard Academy. Chainguard also offers VMs and Libraries — contact us for access.

Trademarks

This software listing is packaged by Chainguard. The trademarks set forth in this offering are owned by their respective companies, and use of them does not imply any affiliation, sponsorship, or endorsement by such companies.