runurl

HTTP on demand
in your shell

url downloads an HTTP resource to a disk cache and prints its local path. run executes programs from URLs, like in a browser.

sh
~ ❯ url https://upload.wikimedia.org/wikipedia/commons/7/7c/Atlantic_Puffin_Illustration.svg
/home/mike/.cache/dev.hydraulic/url-tool/cache/entries/af/2c/af2c4969d14f020b/content/Atlantic_Puffin_Illustration.svg

~ ❯ chafa `url https://upload.wikimedia.org/wikipedia/commons/7/7c/Atlantic_Puffin_Illustration.svg`
Atlantic puffin illustration by Aki G. Karlsson

HTTP's caching protocol is used, so repeated requests return quickly. If the resource has changed it's refreshed.

Link inside archives

Treat zips and tarballs like directories. The archive is downloaded and extracted to the disk cache, and the path is printed.

$ file `url downloads.hydraulic.dev/conveyor/conveyor-22.2-linux-amd64.tar.gz/conveyor-22.2/bin/conveyor`
/Users/mikehearn/…/content/conveyor-22.2/bin/conveyor: ELF 64-bit LSB pie executable, x86-64
Many codecs are supported, including zstd.

Pin the server down

Add a SHA-256 fragment to lock expected content. For a file inside an archive the hash applies to the complete archive.

sh

$ url example.com/tool.tar.gz/bin/tool#sha256=e9e433…602712
…/content/bin/tool
$ url example.com/tool.tar.gz/bin/tool#sha256=e9e433…ffffff
url: SHA-256 mismatch: expected e9e433…ffffff but resolved e9e433…602712

Resolve in bulk

Provide URLs on stdin. Multiple URLs are downloaded in parallel. Comments and blank lines are ignored, so the input doubles as a small lockfile.

sh

$ url <<'EOF'
# pinned inputs
https://a.example/a#sha256=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

# another pinned input
https://b.example/b#sha256=abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789
EOF
…/content/a
…/content/b

Name the URLs to get variable assignments suitable for evaluation in shell scripts.

sh

$ url <<'EOF'
a=https://a.example/a#sha256=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
b=https://b.example/b#sha256=abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789
EOF
a=…/content/a
b=…/content/b

Watch a download

Use --progress=bar for an animated Unicode progress bar while url downloads.

sh · asciicast

Run things like you're on the web

run takes a URL and executes the program found at that location.

sh

$ run hydraulic-software.github.io/url/ hello
Hello from run.zip.
argument: hello
inspect the package ↗

On zsh just use an HTTPS URL as a command directly.

zsh

$ hydraulic-software.github.io/url hello
Hello from run.zip.
argument: hello

The URL has /run.zip/run.js appended. The JS runs in a sandbox and returns a launch plan. It can download more URLs to the disk cache, compose different sources together, and change behavior depending on the host OS/CPU and command line flags.

Launch plans can specify the permissions of the executed program, so run supports sandboxing. Permissions can be dynamic based on command line flags.

Preview the launch plan with --dry-run. This Jinfer example derives permissions from its arguments, then shows which restrictions the host can enforce. Paths are abbreviated; the dry run prints this plan without starting Jinfer.

sh

$ ?jinfer.qxotic.ai --help
DRY RUN  Launch plan

Command
  Executable  …/graalvm-jdk-25.0.4+7.1/Contents/Home/bin/java
  Arguments
     1  -Djinfer.models=~/Library/Caches/ai.qxotic.jinfer/models
     2  -Djava.io.tmpdir=~/Library/Caches/ai.qxotic.jinfer
     3  --add-modules
     4  jdk.incubator.vector,jdk.httpserver
     5  --enable-native-access=ALL-UNNAMED
     6  -jar
     7  …/jinfer-cli-0.3.1.jar
     8  --help

Sandbox
  Rules revision  2026-10-10
  Backend         macOS Seatbelt

Permissions
  Requested
  write
     1  ~/Library/Caches/ai.qxotic.jinfer
  network  client · server
  enforcement  files and network enforced · environment enforced

  Baseline
  read + execute
     1  …/jinfer-cli-0.3.1.jar
     2  …/graalvm-cache-entry/content
     3  system libraries, configuration and programs
  working directory traversal  ~/Hydraulic/url
  private temporary directory  …/hydraulic-run-…
  environment
     1  HOME
     2  LANG
     3  LC_ALL
     4  LC_CTYPE
     5  PATH
     6  TERM
     7  TMPDIR

Writing a package? Give your agent the run-tutorial skill, which explains the format and its conventions.

sh

$ mkdir -p .agents/skills
$ cp -R "$(url hydraulic-software.github.io/url/skills/run-tutorial.zip/run-tutorial/)" .agents/skills/

Reimplementable

Don't like this implementation? No problem.

Give the specification to your favourite model and make a better one that's drop-in compatible.