esolang/unreadable repository overview

⁠Unreadable

• Official website / documentation for Unreadable⁠

This image is part of the esolang-box project⁠ (v2.6.0).

⁠Overview

esolang-box⁠ provides a consistent, Docker-based interface for running 244 programming languages — from mainstream languages to obscure esoteric programming languages⁠.

Every image in the collection follows the same interface:

• First argument — path to the source code file
• stdin — program input
• stdout — program output

This means you can switch between languages without changing how you invoke them. All images are available under the esolang/ namespace on Docker Hub⁠.

The unreadable command (also aliased as script) runs the Unreadable interpreter inside this image.

⁠Usage

⁠Run a script

$ ls
hello.unreadable

$ docker run --rm -v "$PWD":/code:ro esolang/unreadable unreadable /code/hello.unreadable
Hello, World!

⁠Pass input via stdin

$ docker run -i --rm -v "$PWD":/code:ro esolang/unreadable unreadable /code/hello.unreadable < input.txt

⁠Open an interactive shell

Useful for debugging or exploring the image environment.

$ docker run -it --rm -v "$PWD":/code:ro esolang/unreadable sh
# unreadable /code/hello.unreadable
Hello, World!

⁠Trace exec syscalls with strace

esolang-box supports tracing execve and execveat syscalls. Set the STRACE_OUTPUT_PATH environment variable and grant the SYS_PTRACE capability to write a strace log to the specified path.

$ docker run --cap-add=SYS_PTRACE --rm -v "$PWD":/code \
    --env STRACE_OUTPUT_PATH=/code/strace.txt \
    esolang/unreadable unreadable /code/hello.unreadable
Hello, World!

Notes:

• On kernels older than 4.8, enabling ptrace disables the seccomp filter⁠. Avoid using --cap-add=SYS_PTRACE on such systems (e.g. Ubuntu Xenial).
• Strace adds significant overhead — syscalls may run roughly 10× slower than normal.

⁠Disassemble a script

This image includes a disasm command that converts a Unreadable program into a more human-readable form.

$ docker run --rm -v "$PWD":/code:ro esolang/unreadable disasm /code/hello.unreadable