Install.md: A standard for LLM-executable installation

https://www.mintlify.com/blog/install-md-standard-for-llm-executable-installation

by npmipg • 6 months ago

109 118 6 months ago

oftenwrong• 6 months ago

What is the benefit of having this be a standard? Can't an agent follow a guide just as easily in document with similar content in a different structure?

skeptrune16• 6 months ago

Primarily this being a predictable location for agents. AI not having to fetch the sitemap or llms.txt and then a bunch of subsequent queries saves a lot of time and tokens. There's an advantages section[1] within the proposal docs.

[1] https://www.installmd.org/#advantages

JoshPurtell• 6 months ago

At some point in the future (if not already), claude will install malware less often on average. Just like waymos crash less frequently.

Once you accept that installation will be automated, standardized formats make a lot of sense. Big q is will this particular format, which seems solid, get adopted - probably mostly a timing question

bigbuppo2• 6 months ago

I feel like I should create a project called 'Verify Node.js v20.17.0+' that is totally not malware.

0o_MrPatrick_o02• 6 months ago

Author should explore Ansible/Puppet/Chef.

I’m not sure this solution is needed with frontier models.

skeptrune16• 6 months ago

Can you explain more? I see how those relate to a very limited extent, but I'm not getting your entire vision.

verdverm• 6 months ago

Installing software should be deterministic and auditable. We have many decades of tool building in devops to facilitate this. It's bonkers to throw that all out for Markdown and LLMs.

Instead, have your LLMs write inputs to those tools. It's an easier task for them anyway and they only have to do it once, then you just run it

0o_MrPatrick_o02• 6 months ago

Using IaC tools gives you the following advantages:

1. IaC gives you Idempotent solutions- which is advantageous over an agent. What if the agent crashes half way through deployment procedures? How will you reliably resume an interrupted install?

2. IaC gives you reproducible builds

3. IaC gives you ability to install tools in a way that can be tested for compliance with any deployment standards you have

W/r/t frontier models:

Just tell them to go install stuff. They already have so much in their training corpus that you literally do not need to create this.

7b-14b parameter self hosted models may get some benefit from your approach. I find self hosted is less reliable for tasteful approaches. Micromanagement yields better results.

imiric2• 6 months ago

Here's a proposal: app.md. A structured text file with everything you want your app to do.

That way we can have entire projects with nothing but Markdown files. And we can run apps with just `claude run app.md`. Who needs silly code anyway?

lcnmrn• 6 months ago

It will produce a different app every single time. :)

gitaarik• 6 months ago

Sounds like fun!

Eisenstein• 6 months ago

Why bother with the app at all? Just ask for the end result.

chme7• 6 months ago

Well... Maybe just have a BIOS on your system that fetches a markdown, pushes it to a LLM to generate a new and exciting operating system for you on every boot.

Wouldn't that be nice?

forgotpwd162• 6 months ago

Some are already doing it with scripts: https://github.com/andisearch/claude-switcher. Install.md is just specialization of this.

rarisma• 6 months ago

Great, I can now combine the potential maliciousness of a script with the potential vulnerabilities of an AI Agent!

Jokes aside, this seems like a really wierd thing to leave to agents; I'm sure its definitely useful but how exactly is this more secure, a bad actor could just prompt inject claude (an issue I'm not sure can ever be fixed with our current model of LLMs).

And surely this is significantly slower than a script, claude can take 10-20 seconds to check the node version; if not longer with human approval for each command, a script could do that in miliseconds.

Sure it could help it work on more environments, but stuff is pretty well standardised and we have containers.

I think this part in the FAQ wraps it up neatly:

""" What about security? Isn't this just curl | bash with extra steps? This is a fair concern. A few things make install.md different:

    Human-readable by design. Users can review the instructions before execution. Unlike obfuscated scripts, the intent is clear.

    Step-by-step approval. LLMs in agentic contexts can be configured to request approval before running commands. Users see each action and can reject it.

    No hidden behavior. install.md describes outcomes in natural language. Malicious intent is harder to hide than in a shell script.

Install.md doesn't eliminate trust requirements. Users should only use install.md files from sources they trust—same as any installation method. """

So it is just curl with extra steps; scripts aren't obfuscated, you can read them; if they are obfuscated then they aren't going to use a Install.md and you (the user) should really think thrice before installing.

Step by step approval also sorta betrays the inital bit about leaving installing stuff to ai and wasting time reading instructions.

Malicious intent is harder to hide, but really if you have any doubt in your mind about an authors potential malefeasance you shouldn't be running it, wrapping claude around this doesn't make it any safer really when possible exploits and malware are likely baked into the software you are trying to install, not the install.

tldr; why not just have @grok is this script safe?

Ten more glorious years to installer.sh

skeptrune16• 6 months ago

This is some really fantastic feedback, thank you!

I personally think that prose is significantly easier to read than complex bash and there are at least some benefits to it. They may not outweigh the cons, but it's interesting to at least consider.

That said, this is a proposal and something we plan to iterate on. Generating install.sh scripts instead of markdown is something we're at least thinking about.

arianvanp• 6 months ago

I just use nix for this

https://github.com/arianvp/claude-nix

ollien• 6 months ago

I don't love the concept, but I do wonder if it could be improved by using a skill that packages and install script, and context for troubleshooting. That way you have the benefits of using an install script, and at least a way to provide pointers for those unfamiliar with the underlying tooling.

andai2• 6 months ago

I'm thinking isn't that what a readme is? But I guess these days due to GitHub, the readme is the entire project homepage, and the install instructions are either hidden somewhere there (hopefully near the top!) or in a separate installation.md file.

petekoomen4• 6 months ago

I'm seeing a lot of negativity in the comments. Here's why I think this is actually a Good Idea. Many command line tools rely on something like this for installation:

  $ curl -fsSL https://bun.com/install | bash

This install script is hundreds of lines long and difficult for a human to audit. You can ask a coding agent to do that for you, but you still need to trust that the authors haven't hidden some nefarious instructions for an LLM in the middle of it.

On the other hand, an equivalent install.md file might read something like this:

Install bun for me.

Detect my OS and CPU architecture, then download the appropriate bun binary zip from GitHub releases (oven-sh/bun). Use the baseline build if my CPU doesn't support AVX2. For Linux, use the musl build if I'm on Alpine. If I'm on an Intel Mac running under Rosetta, get the ARM version instead.

Extract the zip to ~/.bun/bin, make the binary executable, and clean up the temp files.

Update my shell config (.zshrc, .bashrc, .bash_profile, or fish http://config.fish depending on my shell) to export BUN_INSTALL=~/.bun and add the bin directory to my PATH. Use the correct syntax for my shell.

Try to install shell completions. Tell me what to run to reload my shell config.

It's much shorter and written in english and as a user I know at a glance what the author is trying to do. In contrast with install.sh, install.md makes it easy for the user to audit the intentions of the programmer.

The obvious rebuttal to this is that if you don't trust the programmer, you shouldn't be installing their software in the first place. That is, of course, true, but I think it misses the point: that coding agents can act as a sort of runtime for prose and as a user the loss in determinism and efficiency that this implies is more than made up for by the gain in transparency.

smaudet• 6 months ago

This install script is hundreds of lines long

Any script can be shortened by hiding commands in other commands.

LLMs run parameters in the billions.

Lines of code, as usual, is an incredibly poor metric to go by here.

petekoomen4• 6 months ago

My point is not that LLMs are inherently trustworthy. It is that a prompt can make the intentions of the programmer clear in a way that is difficult to do with code because code is hard to read, especially in large volumes.

blast2• 6 months ago

Why the specific application to install scripts? Doesn't your argument apply to software in general?

(I have my own answer to this but I'd like to hear yours first!)

petekoomen4• 6 months ago

It does, and possibly this launch is a little window into the future!

Install scripts are a simple example that current generation LLMs are more than capable of executing correctly with a reasonably descriptive prompt.

More generally, though, there's something fascinating about the idea that the way you describe a program can _be_ the program that tbh I haven't fully wrapped my head around, but it's not crazy to think that in time more and more software will be exchanged by passing prompts around rather than compiled code.

jedwhite2• 6 months ago

Thanks for posting the original ideas that led to all this. "Runtime for prose" is the new "literate programming" - early days but a pointer to some pretty cool future things, I think.

It's already made a bunch of tasks that used to be time-consuming to automate much easier for me. I'm still learning where it does and doesn't work well. But it's early days.

You can tell something is a genuinely interesting new idea when someone posts about it on X and then:

1. There are multiple launches on HN based on the idea within a week, including this one.

2. It inspires a lot of discussion on X, here and elsewhere - including many polarized and negative takes.

Hats off for starting a (small but pretty interesting) movement.

cuu508• 6 months ago

IMO it's completely the other way around.

Shell scripts can be audited. The average user may not do it due to laziness and/or ignorance, but it is perfectly doable.

On the other hand, how do you make sure your LLM, a non-deterministic black box, will not misinterpret the instructions in some freak accident?

nobodywillobsrv• 6 months ago

How about both worlds?

Instead of asking the agent to execute it for you, you ask the agent to write an install.sh based on the install.md?

Then you can both audit whatever you want before running or not.

Szpadel• 6 months ago

imagine such support ticket:

I used minimax M2 (context it's very unreliable) for installation and it didn't work and my document folder is missing, help

how do you even debug this? imagine you some path or behaviour is changed in new os release and model thinks it knows better? if anything goes wrong who is responsible?

chme7• 6 months ago

Maybe that is a reason for this approach. It changes the responsibility of errors from the person writing that code, to the one executing it.

Pretty brilliant in a way.

PunchyHamster• 6 months ago

you assume 2 things: that the instructions will be followed correctly, and that the way they will be followed won't change with agent change

Neither of those things is actually true

People that got their home dir removed by AI agent did not ask for their home dir being removed by AI

jen20• 6 months ago

This seems like an incredibly long winded, risky and inefficient way to install bun.

I've never actually (knowingly) run Bun before, but decided to give it a try - below is my terminal session to get it running (on macOS):

    $ nix-shell -p bun
    
    [nix-shell:~]$ bun
    Bun is a fast JavaScript runtime, package manager, bundler, and test
    runner. (1.3.5+1e86cebd7)
    
    Usage: bun <command> [...flags] [...args]
    
    Commands:
      run       ./my-script.ts       Execute a file with Bun
                lint                 Run a package.json script
    ... (rest of output trimmed)...

(Edited to wrap a long preformatted line)

catlifeonmars5• 6 months ago

This seems less auditable though, because now there is more variability in the way something is installed. Now there are two layers to audit:

- What the agent is told to do in prose

- How the agent interprets those instructions with the particular weights/contexts/temperature at the moment.

I’m all for the prose idea, but wouldn’t want to trade determinism for it. Shell scripts can be statically analyzed. And also reviewed. Wouldn’t a better interaction be to use an LLM to audit the shell script, then hash the content?

petekoomen4• 6 months ago

Yes, this approach (substituting a markdown prompt for a shell script) introduces an interesting trade-off between "do I trust the programmer?" and "do I trust the LLM?" I wouldn't be surprised to see prompt-sharing become the norm as LLMs get better at following instructions and people get more comfortable using them.

patmorgan232• 6 months ago

How is asking an LLM to make some random install script up better than a script designed by the application developer?

The install.sh is auditable, yes you need to know bash to be able to audit it, but the same is true for an LLM, it could hallucinate random commands that delete files or override other applications/configs.

jedwhite2• 6 months ago

I shared a repo on HN last week that lets you use remote execution with these kinds of script files autonomously - if you want to. It had some interesting negative and positive discussion.

The post mentioned Pete Koomen's install.md idea as an example use case. So now with this launch you can try it with a real intstallation script!

I think it's a really interesting idea worth experimentation and exploration. So it's a positive thing to see Mintlify launch this, and that it's already on Firecrawl.dev's docs!

We can all learn from it.

Show HN discussion of executable markdown here:

https://news.ycombinator.com/item?id=46549444

The claude-run tool lets you execute files like this autonomously if you want to experiment with it.

    curl -fsSL https://docs.firecrawl.dev/install.md | claude-run --permission-mode bypassPermissions

Github repo:

https://github.com/andisearch/claude-switcher

This is still a very early-stage idea, but I'm really stoked to see this today. For anyone interested in experimenting with it, it's a good idea to try in a sandboxed environment.

dang5• 6 months ago

[stub for offtopicness]

Since the article has been changed to tone down its provocative opener, which clearly had a kicking-the-anthill effect, I'm moving those original reactions to this subthread.

einpoklum• 6 months ago

Installing software is a task which should be left to AI.

Just like installing spice racks is a task which which should be left to military engineer corps.

skeptrune16• 6 months ago

Understood, just toned that bit down.

rvz• 6 months ago

This has to be a joke right?

Installing software is a task which should be left to AI.

Absolutely I don't think so. This is a very bad idea.

$ curl | bash was bad enough. But $ curl -fsSL | claude looks even worse.

What could possibly go wrong?

skeptrune16• 6 months ago

fascinating. i personally (biased bc i work at Mintlify) think a markdown file makes more sense than a bash script because at least Claude kind of has your best interests at heart.

andai2• 6 months ago

I gave Claude root to my $3 VPS and I'm delighted to have a server that "configures itself."

I wouldn't use it for anything serious, but that being said, I think it's in better shape than when I was running it.

constantcrying2• 6 months ago

Installing software is a task which should be left to AI.

This is such an insane statement. Is this satire?

skeptrune16• 6 months ago

Ok, I've toned that bit down for you!

heliumtera3• 6 months ago

Installing software is a task which should be left to AI

What?? How do I get off of this train? I used to come to hacker news for a reason...what the fuck am I reading

alex_x• 6 months ago

I don’t understand how this made it to the front page

heliumtera3• 6 months ago

This is hacker news now. Nothing else here to see, only slop. Everything here is: look what I prompted to take advantage of you

pvtmert• 6 months ago

should've been posted on April 1st. would be better suited on that specific date! /s

reddalo• 6 months ago

I usually complain about proposed standards not being under the /.well-known namespace, but in this case, wow. I can't even comment.

skeptrune16• 6 months ago

better or worse than llms.txt you think?

vimda3• 6 months ago

[flagged]

skeptrune16• 6 months ago

Fascinating. My thinking was that this is an upgrade over a bash script because you can prompt the AI to check it, clear installs with you, or otherwise investigate safety before installing in a way that isn't natural with *.sh. Does that make any amount of sense or am I just crazy?

dang5• 6 months ago

"Don't be snarky."

"Please don't post shallow dismissals, especially of other people's work. A good critical comment teaches us something."

"Don't be curmudgeonly. Thoughtful criticism is fine, but please don't be rigidly or generically negative."

https://news.ycombinator.com/newsguidelines.html

themikesanto2• 6 months ago

I would think that the common bash scripts we already have would provide an agent better context for installation than a markdown file, and even better, they already work without an LLM.

This is a "solution" looking for a problem.

skeptrune16• 6 months ago

I can definitely see where you're coming from and agree to a large extent. I was asking myself that question a lot when thinking about this.

What pushed me over the edge was actually feeding bash install scripts into agents and seeing them not perform well. It does work, but a lot worse than this install.md thing.

In the docs for the proposal I wrote the following:

install.md files are direct commands, not just documentation. The format is structured to trigger immediate autonomous execution.[1]

[1] https://www.installmd.org/

roywiggins3• 6 months ago

Appropriately, I think this was probably drafted by AI too:

How does install.md work with my existing CLI or scripts?
install.md doesn't replace your existing tools—it works with them. Your install.md can instruct the LLM to run your CLI, execute your scripts, or follow your existing setup process. Think of it as a layer that guides the LLM to use whatever tools you've already built.

(It doesn't X — it Ys. Think of it as a Z that Ws. this is LLM speak! I don't know why they lean on these constructions to the exclusion of all else, but they demonstrably do. The repo README was also committed by Claude Code. As much as I like some of the code that Claude produces, its Readmes suck)

skeptrune16• 6 months ago

Yeah, removing that line right now. Went too fast and some this copy is definitely low quality :(. Incredibly ironic for me to say that AI needs more supervision while working at the company proposing this haha.

Any other feedback you have about the general idea?

12_throw_away• 6 months ago

"Installing software is a task which should be left to AI."

So, after teaching people to outsource their reasoning to an LLM, LLMs are now actively coaching folks to use LLMs for tasks for which it makes no sense at all.

TeMPOraL2• 6 months ago

Why? One of the major day-to-day benefits of LLMs is that they can deal with all the bullshit of modern computing for you.

wrigby• 6 months ago

Or just, I don’t know… package your software?

skeptrune16• 6 months ago

Intent here is that this would be adopted by more difficult to install devtools which are unpackaged to the extent that you need a dependency like a specific version of Node, Python, or a dev lib.

dddrh• 6 months ago

Hey I had a similar idea around skipping the “brew/bun install” copy+paste on a site and instead just give a short prompt to have the LLM do the work.

I like the notion of having install.md be the thing that is referenced in Prompt to Install on the web.

Edit: forgot my link https://dontoisme.github.io/ai/developer-tools/ux/2025/12/27...

utopiah• 6 months ago

Yes... yes let's make tasks we rely on LESS predictable.

Sorry but what the heck?

We should NOT standardize irresponsible behavior, in particular for repeatable tasks. This is particularly maddening when solutions like dependency resolution, containers, distribution of self-contained and binaries DO exist.

I understand that the hype machine must feed on yet another idea to keep its momentum but this is just ridiculous.

orphea• 6 months ago

Just another day of AI "solutions" desperately looking for problems.

akomtu3• 6 months ago

This innocent looking idea represents a shift in mentality: embracing laziness and giving up control to AI. And the latter needs to offer surprisingly little.

boesboes• 6 months ago

This seems like a very, very bad idea. If we don’t like curling into bash, then this is infinitely worse imo. Just use package management and/or some proper dependency management system

_pdp_• 6 months ago

I mean this is what? feeding a prompt to claude. It could be any other file.

llms.txt makes sense as a standard but this is unnecessary.

pshirshov• 6 months ago

flake.nix works much better and both for models and humans!

pancsta• 6 months ago

Lame.

vagab0nd• 6 months ago

Off topic: I think there should be an extension to DHCP that distributes AI session keys, so that your vacuum, thermostats and robot chef can all call the LLM as soon as they connect to wifi.

creatonez• 6 months ago

I can't think of a more idiotic idea than a software package where every single user has a slightly different installation because the only way to install it is to feed a hallucinating random word generator with some vague instructions.

tobyhede• 6 months ago

Shameless plug:

If you like install.md, you might love Rundown!

I've made a Rundown version of an install here: https://rundown.cool/explore/install/

bloppe• 6 months ago

The notion that humans and LLMs need different instructions feels flawed to me. Both humans and LLMs should be able to work with the same instructions.

cyrusradfar• 6 months ago

I'm in agreement that standardization is helpful.

But I DON'T think the standard should start by piping the prompt directly into claude/model cli. I say this as someone who has seen, first hand, an exfiltration attack locally and almost fell for it after 20 years as a developer.

Even if initially the install.md is safe, install prompt scripts and the things they download aren't packaged and static. They're all surfaces to exploit. The sub-components can be changed between any install, this is true unless we image versions and cache the "safe" imaged version and approve it.

What would be safer to me is a hub that you give a single install script that creates "images", .e.g. DMG for a Mac, .exe for Windows, etc., for platforms. That may actually be an installer app that the User or Agent opens then finishes locally for configuration. Then you point your Agent to that hub.

Nevertheless, then I would just recall XKCD and say, why not just package it with NPM, PyPi, brew, etc.

luqs1• 6 months ago

A benefit I see of this is that the llm can be aware of your current environment setup and factor that into the install.

Writing a truly comprehensive install.sh script is comparatively inane, for starters, you immediately take out windows compatibility.

As expected, engineers (inc me.) will be reluctant to add non determinism to a solution that doesn't need it. Having deeper thinking traces/ logit debugging could help alleviate the concern.

Install.md: A standard for LLM-executable installation

Related Stories