Oneshot

2025-02-26

Ever wanted to just run a script or cli utility really quickly in a container? Maybe you want to avoid polluting your userspace with dependencies, or you just want to try something new because it's too early to commit.

I'd like to introduce oneshot...

Oneshot is a command-line utility to fire off a script in a short-lived container.

Oneshot can run commands

A basic hello world example that will output to console.

# Hello world
oneshot run -s "echo HELLO WORLD"

You can quickly install packages using --from-uv, --from-apk, --from-cargo, --from-bun, and a few others.

# Cowsay hello World
oneshot run -s "uvx pycowsay 'Hello from oneshot!'" --from-uv pycowsay

Oneshot can boot an interactive shell

You can start a shell in the container.

oneshot shell

You can start a REPL, having installed some packages.

# With numpy
oneshot run -s "python3 -i" --from-uv numpy

Oneshot command examples

Download a YouTube video

oneshot run -s "yt-dlp dQw4w9WgXcQ" --from-uv yt-dlp

Then compress it

oneshot run -s "ffmpeg -i input.mp4 output.webm" --from-apk ffmpeg

Convert an image format

oneshot run -s 'convert input.png output.jpg' --from-apk imagemagick

Convert markdown to PDF

oneshot run -s "pandoc -s input.md -o output.pdf" --from-apk pandoc

Future

Ideally, I'd love to add these two features to oneshot:

1. The exec subcommand that should execute a script in a oneshot container.
2. A shebang which allows you to pass args in to configure the oneshot, essentially making oneshot a one-liner at the top of a script.

I also stopped development just short of adding a Docker adapter and build script. If anyone wants, feel free to create a PR for these.

• Git repo