Atuin Desktop: Runbooks That Run

157 comments

·April 22, 2025

floathub

For anyone emacs-curious, you can do a similar thing with org-babel

You can have a plaintext file which is also the program which is also the documentation/notebook/website/etc. It's extremely powerful, and is a compelling example of literate programming.

A good take on it here: https://osem.seagl.org/conferences/seagl2019/program/proposa...

zelphirkalt

Actually, in terms of capabilities, org-babel is among the most capable, if it is not the most capable, systems for literate programming. I have used it to great effect when learning from computer programming books. I can now go back to those literate programs, and understand again much faster, than originally when reading the books. The literate part of it answers my "silly" questions, that come from not remembering 100% of the reasoning or my own thoughts. That said, there is of course a learning curve, and people unwilling to learn something like that are better off not going that route.

spudlyo

Thanks for the shout-out! I think org-babel is really well suited for this task, and can make some really great documentation. You can check out the video[0] from the talk and a git repo[1] with a more advanced demonstration.

[0]: https://www.youtube.com/watch?v=0g9BcZvQbXU

[1]: https://gitlab.com/spudlyo/orgdemo2

floathub

Thanks for making the presentation. I found it very useful when I first started messing around with babel, and I still come back to it from time to time.

kstrauser

Similar with BBEdit's Shell Worksheets, which mingle prose with commands you can run with a keypress.

ymarketing

[dead]

amirathi

I took a stab at this ~7 years ago - https://nurtch.com/

The idea has a lot of merit. We even gave a talk about it in JupyterCon Paris 2023 - https://www.youtube.com/watch?v=TUYY2kHrTzs

When you have executable code in the documentation, folks want to follow PR-review workflow with the docs as well - which is a bit more team investment than editing a wiki.

Good luck!

wodenokoto

My first thought was also "why not jupyter"? Nice to see someone else had the same thought!

huntaub

This is exactly what I wanted for our team when I was at AWS. There are so many versions of operations which are just slightly too dangerous to automate, and this provides a path to iteratively building that up. Congratulations!

rochak

Preface: My opinions are my own and not my employer’s.

Curious how long ago were you at AWS? For context, I spent the last few years in AWS working on an internal platform service whose entire purpose was to reduce operational toil by helping you codify your operational runbooks and execute them safely and automatically. Atuin Desktop is similar to that service in some sense but that service just offered much more features.

perpil

Not OP but was there 15 years (left Dec 2021) and surprised I wasn't aware of this. I was only aware of a few tools that acted like chatbots to automatically gather context or take action from chime/tt/alarms.

perpil

When I was at AWS, I built something so I could run things straight from the wiki. Think cloudwatch queries, aws cli commands etc with user inputs but without all the setup of securely getting the right credentials and formatting inputs. I've rebuilt to run stuff straight from GitHub. Here's it invoking a lambda function straight from a github wiki with user input in 4 lines of code: https://speedrun.nobackspacecrew.com/index.html#invoking-an-...

simsla

When I was at Amazon (pre covid), Eider could've been used for that.

(Hosted notebooks with IAM integration.)

dheerkt

How is this different from a local Jupyter notebook? Can we not do this with ! or % in a .ipynb?

Genuine question. Not familiar with this company or the CLI product.

berkes

The main thing that keeps me from using Jupyter notebooks for anything that's not entirely Python, is Python.

For me, pipenv/pyenv/conda/poetry/uv/dependencies.txt and the invitable "I need to upgrade Python to run this notebook, ugh, well, ok -- two weeks later - g####m that upgrade broke that unrelated and old ansible and now I cannot fix these fifteen barely held up servers" is pure hell.

I try to stay away from Python for foundational stuff, as any Python project that I work on¹ will break at least yearly on some dependency or other runtime woe. That goes for Ansible, Build Pipelines, deploy.py or any such thing. I would certainly not use Jupyter notebooks for such crucial and foundational automation, as the giant tree of dependencies and requirements it comes with, makes this far worse.

¹ Granted, my job makes me work on an excessive amount of codebases, At least six different Python projects last two months, some requiring python 2.7, some requiring deprecated versions of lib-something.h some cutting edge, some very strict in practice but not documented (It works on the machine of the one dev that works on it as long as he never updates anything?). And Puppet or Chef - being Ruby, are just as bad, suffering from the exact same issues, only that Ruby has had one (and only one!) package management system for decades now.

RestartKernel

Jupyter Notebooks have always felt a bit hacky for terminal purposes to me, so I'm excited to give this a shot.

BOOSTERHIDROGEN

How about marimo?

hashstring

100% same question.

Usually, I feel like Jupyter gives both worlds—- flexible scripting and support for os commands (either through !/% or even os.system()

celera

This looks super similar to https://runme.dev

sourishkrout

Thanks for the shout-out. Co-creator of Runme here .

Love runnable documentation. We don't have enough of it.

mkl

I didn't find the hero video on https://runme.dev/ very helpful. I think it would be much easier to understand what Runme is for if you replaced the video with the "Make Markdowns Interactive" demos.

sourishkrout

Will look into it. The feedback is much appreciated. Thank you!

binaryblitz

Your playground says the login is "Only used for verification against abuse."

Immediately after signing in, I get an email from you. Serious uncool and an instant "nope" from me after that.

nathabonfim59

This is amazing!

Exactly what I was looking for, thanks!

elAhmo

Looks interesting!

We recently started using https://marimo.io/ as a replacement for Jupyter notebooks, as it has a number of great improvements, and this seems like a movement in a similar direction.

0xbadcafebee

If it's local-first then it's already subject to rot. Unless they're running it all in containers? In which case local doesn't matter.

If you want to record a runbook, then record a runbook. You can do that a million ways. Text file, confluence doc, screen recording, shell script, etc. People already don't do that; they're not gonna suddenly start doing it more because your UI is fancier.

Personally, I don't want to sit around all day writing code (or docs) to try to get the system to be like X state. I want to manually make it have X state, and then run a tool to dump the state, and later re-run the tool to create (or enforce) that state again. I do not want to write code to try to tell the computer how to get to that state. Nor do I want to write "declarative configuration", which is just more code with a different name. I want to do the thing manually, then snapshot it, then replay it. And I want this to work on any system, anywhere, without dependence on monitoring a Bash shell for commands or something. Just dump state and later reapply state.

LinXitoW

So you then have binary blobs of state without any documentation of how or why it is the way it is? That doesn't seem maintainable.

Dockerfiles are basically this, but with a file documenting the different steps you took to get to that state.

0xbadcafebee

Then I should explain why "a blob" is, in a weird way, actually superior to a Dockerfile.

Step 1. You write a Dockerfile. You build it. You test with it. Hey, it works! You push it to production.

Step 2. Years later, you need to patch that container in production. So you change the Dockerfile, rebuild, and re-test.

Step 3. Uh-oh! The tests don't work anymore! What's going on? I changed one line in the Dockerfile but now the app isn't working (or perhaps the build isn't). What's going on?

What's going on is a reproducibility failure. Just having the instructions (or what someone thought was the instructions, or what they were years ago) isn't enough to ensure you get the same results a second time. A million little things you didn't think of may change between builds (and the more time in-between, the more things change), and they may end up breaking things. Without a truly reproducible build, you are likely to have problems trying to rebuild with just the instructions.

That's why with Docker containers, we rely on build artifacts. The container you had two years ago? However that was built, with whatever weird combination of arguments and files-on-the-internet-being-pulled-at-build-time and everything else, it was built successfully. If you want to be really sure you patch it correctly, you pull the old container image (not Dockerfile), modify that, and push that to production as a new container. No rebuilding, just patching. This avoids reproducibility failures.

That same idea is why you'd want to just download a blob and later re-apply it.

The blob was the state of things when it was working. If you tried to just write down the instructions to replicate it, it's likely you'd either 1) get it wrong (it was only working because of some unrelated changes somebody else made and forgot about) or 2) you'd get a reproducibility error.

So "the blob" I'm talking about doesn't have to be a literal binary blob. It could be whatever, we're talking about a theoretical idea here. It could be layers like a container, or metadata in a JSON file, or configuration/code that gets auto-generated, etc. I don't care what it is. It just has to describe the state as it was when X was working. It's then up to the tool to figure out how to get back to that state.

People already write this as "declarative code" for configuration management tools to do the same thing. I'm saying, I don't want to have to write the code. Just dump it out for me.

dewey

That’s not what they are saying. They are saying that the system where you have to declare everything manually is annoying (which it is), ideally it would record the changes while you make changes and then deduplicate them, remove unnecessary ones to arrive at the final playbook that can be replayed if needed.

naikrovek

yes it would be nice to have a computer that could read your mind flawlessly.

pram

Sounds like you want autoexpect!

https://linux.die.net/man/1/autoexpect

0xbadcafebee

Actually no, that's still just monitoring a series of steps to eventually lead to a thing. I don't want to record a series of steps, I just want to dump existing state of a thing.

zelphirkalt

Such a process is rarely portable though, and will need to be repeated for each different system, at which point it would be great to already have a declarative description, that can automatically be translated into those steps required to get to state X.

jimbokun

That was the Docker manifesto.

x-complexity

> That was the Docker manifesto.

It essentially still is.

Unless the Dockerfiles are kept secret, any container can be replicated from the given Dockerfile. Barring extreme (distro/system/hardware)-level quirks, a Docker container should be able to run anywhere that Linux can.

manquer

You are mixing build time reproduction with run time ones.

Docker images (not files) help with the run time consistency .

Docker (files) barely scratch the surface of build reproducibility. Most applications depend on the distribution package manager ( apt, apk etc) and language package manager (npm, cargo, etc), both sets of them have various challenges in consistent dependency resolution.

In addition build steps might have ordering challenges RPC calls to remote services no longer running and so on.

Anyone trying to to build a docker image from 10 years back experiences this problem

spott

A container can very rarely be reproduced by a dockerfile.

I imagine with a lot of discipline (no apt update, no “latest” tag, no internet access) you can make a reproducible docker file…. But it is far from normal.

retrochameleon

It kind of sounds like you're describing Ansible. You use modules for common tasks like ensuring a package is installed, a file is present or has certain content, etc. It's declarative and imdempotent.

bobthecowboy

I've written some fairly complex stuff in Ansible. It is mostly declarative but you should be careful with assumptions about its idempotency, especially if you reach out for community modules.

0xbadcafebee

No, I don't want to write Ansible configuration. I don't want to write any configuration. I just want to dump state and restore it. (To put it another way: I want to auto-generate ansible configuration based on an existing system, and then apply that configuration again later)

retrochameleon

Well now it just sounds like you're describing a system backup and restore.

milkshakes

what happens when you want to tweak something you did in the middle of this process? do you have to go through the whole flow again manually to make a single change?

0xbadcafebee

I imagine you could either A) just modify the dumped state, B) paramaterize it, C) have the program split up the state into transactions and modify those. The program will probably have to take more than one step, in order, in order to accomplish everything. If it fails, you'd want it to try to undo it, ala transactions. And since it can do all that, it can stop, start, or resume at specific steps.

Like, Terraform has always sucked because there was no way to dump existing resources as new code. So a team at Google made a tool to do it (Terraform-er). If Terraform had already had that feature, and if it didn't rely on having pre-existing state to manage resources, that would be like 90% of the way to what I'd want. Just dump resources as code, then let me re-run the code, and if I want I can modify the code to ask me for inputs or change things. (People think of Terraform as only working on Cloud resources, but you could (for example) make an Ubuntu Linux provider that just configures Ubuntu for you, if you wanted)

kiitos

Any notion of state that satisfies requirements like

> Just dump state and later reapply state

is necessarily declarative.

> Just dump resources as code,

What is the code for this resource?

    VM foo1
        Memory  16GiB
        Network mynet1

It depends on the current state of the system where the resource is applied. If VM foo1 already exists, with 16GiB of memory, and connected to network mynet1, then the code is a no-op, no code at all. Right? Anything else would be a mistake. For example if the code would delete any matching VM and re-create it, that would be disastrous to continuity and availability, clearly a non-starter. Or, if VM foo1 exists, with 16GiB of memory, but connected to anothernet3, then the code should just change the network for that VM from anothernet3 to mynet1, and should definitely not destroy and re-create the VM entirely. And so on.

sorrythanks

> If it's local-first then it's already subject to rot.

Can you expand on this?

0xbadcafebee

When most people say "local" what they mean is "i'm running something on my laptop". That is to say, it's a random operating system, with a randomly set-up environment, with randomly installed tools. Could be different tools that have the same name but incompatible options. Could be any version (version 3 might be incompatible with version 4, but it's the same name for the command). And it will definitely change over time.

This will lead whatever steps you've recorded to 1) stop working on the existing "local" machine, and 2) be incompatible with other people's "local" machines. So the instructions have "rotted".

To avoid this you could write Ansible/Puppet to install and configure all the same tools, but that will break too over time too, and be a maintenance hassle. The only reliable solution is to use containers to run it all in; that guarantees the same version of everything. But at that point it's not really "running locally" anymore, it's running in the container, which is sort of its own bag of issues.

At that point you might as well have a SaaS tool to run your runbook in a cloud environment in containers or something, as that's way easier to set up and manage than either ansible/puppet, or Docker on everyone's machine (there's still a million tech "engineers" out there who don't understand containers).

IOT_Apprentice

Pre Cloud at eBay we managed 30k windows servers via a tool called site controller that referenced ALL servers as objects with properties of configuration state, build version and operational state.

ALL databases had their startup configuration parameters defined per instance across datacenters.

Furthermore SRE had tools to rate limit connections or restart of a database so that it was not overwhelmed by incoming connection requests. We also built tools to do fine grained definition of load balancers and what services were behind them to be able to redirect traffic on the fly and then reset to the original mappings once connectivity of the LBs was resolved.

These tools weee centralized and available to both SRE and senior system administrators.

These things evolved to new tools which accommodated a private cloud, then docker then Kubernetes. I left prior to kubernetes implementation.

sorrythanks

I see, I hear you. That isn't what local-first means, though. This is what local-first means:

• https://www.inkandswitch.com/essay/local-first/

• https://www.youtube.com/watch?v=NMq0vncHJvU

freedomben

Will this be open source like Atuin CLI and the sync server are? Is this going to be productized?

jamietanna

It'll be Open Source'd: https://news.ycombinator.com/item?id=43766200#43766584

brunoqc

Probably not the server though.

gniting

Most likely not free. Regardless, happy to see this be announced!

iamwil

Are you worried about getting rug pulled by the platform?

null

[deleted]

freedomben

Yes, enshittification potential is top of mind for me now when considering adopting any product. If it's open source then I worry less.

account-5

I can't say I see the point in this. Can someone explain what I'm missing? Why would I use this over a simple shell script?

joh6nn

My experience with runbooks has been:

- I am on a team that oversees a bunch of stuff, some of which I am very hands-on with and comfortable with, and some of which I am vaguely aware exists, but rarely touch

- X, a member of the latter category, breaks

- Everyone who actually knows about X is on vacation/dead/in a meeting

- Fortunately, there is a document that explains what to do in this situation

- It is somehow both obsolete and wrong, a true miracle of bad info

So that is the problem this is trying to solve.

Having discussed this with the creator some[1], the intent here (as I understand it) is to build something like a cross between Jupyter Notebooks and Ansible Tower: documentation, scripts, and metrics that all live next to each other in a way that makes it easier to know what's wrong, how to fix it, and if the fix worked

[1]Disclosure: I help mod the atuin Discord

BLanen

If the fix/solution would be easily describable and automate-able, it wouldn't/shouldn't be a problem anyway. I don't see how this solves anything.

soupdiver

It shouldn't but often still is... and maybe a runbook like this is easier to handle than a script with possibly 1000 lines and not a single comment. Of course, in your ideal world maybe nothing of this applies and you never have any incidents ;)

mmooss

> It is somehow both obsolete and wrong, a true miracle of bad info

How does Atuin solve that problem? It seems to me that inaccurate and obsolete information can be in an Atuin document as easily as in a text document, wiki, etc., but possibly I'm not seeing something?

joh6nn

I'm just a community mod, not a dev on the project, so take this with a grain of salt:

I believe the intent is that you get bidirectional selective sync between your terminal and the docs, so that if what's in the docs is out of date or wrong, then whatever you did to actually fix things can be synced back to the docs to reduce the friction of keeping the docs updated.

roblh

To me, it seems like it's because the thing you're fixing is actually the "runbook" that's being run. Instead of separating the documentation from the code, they're married together so it's easier to keep them in sync because you aren't having to remind yourself to go edit this secondary location when you make a quick change.

I'm cautiously curious about something like this, although I haven't tried it personally.

account-5

Ok I think I see where this is coming from. I actually think seeing you description that it might even be a benefit to none technical people with no knowledge of what's going on. They can follow instructions and easily execute the relevant code what with it all sitting together.

However I don't see how it solves the obsolete or wrong documentation thing. You still have to make sure the runbook is correct, if it's not you've got the exact same problem.

Having a centralised place for all your scripts is an advantage with inline docs. But then this is a local desktop version...

jimbokun

Seems like this is literate programming for shell scripts.

Thus “Runbooks That Run.”

rc00

Because it's written in Rust and this is Hacker News.

account-5

I was going to talk about using powershell but just for the rust I also really like Nushell. I personally would take either one over this...

johnQdeveloper

Well, what is the purpose of deployments being built in ansible or deployer or whatever tooling as a general rule? And then packaging, say, extra python scripts to perform common tasks then dumping it all in a git repo?

Some people just like a particular workflow or tooling flow and build it really. Maybe it works for enough people to have a viable market, maybe not.

I am just using a PHP deployment process for no reason other than feeling like it for personal projects and it handles 60% of the work without me needing to do anything. But any runbooks for it are tasks built into the tool and in the same git repo for the entire server deployment. I'm not gonna put it in some random place or a shell script that I need to remember separate commands for.

Code, for programmers, is inherently self-documenting if you keep a simple functional style without any complexity with comments on the occasional section that isn't just "Create a MySQL user, roll the MySQL user's password, update the related services with the new password/user combination, remove the old user that the fired employee has credentials to on the off chance we failed to block them at the VPN" kind of stuff.

pm90

My dream tooling is for every tool to have an terminal interface so that I can create comprehensive megabooks to get all the context that lives in my head. i.e. jira, datadog, github etc, all in one pane.

rochak

+1. Personally, I’m a fan of TUIs too that make things a bit more user friendly. Just imagine an internal TUI framework that has components for each internal service that you can lego-build into personalised TUI dashboard. Hmm, seems like something I could work on the side at work. Would be a huge undertaking but very interesting.

pm90

Yes this is what I was thinking. This is how terraform became the lingua franca of iac, I was hoping that something like this would happen with TUIs too, so instead of all vendors creating their own bespoke cli, they all implemented a plugin of some generic TUI framework.

npodbielski

IMHO just an API would be enough, tool could be written on top of that. My ideal world would be every service, tool and application to have API that I can use i.e. if fridge is open too long (API polling or API webhook) I can send roomba to close it (using API of roomba). Because why not?!

World of API...

turtlebits

Not sure what you mean- github and datadog already have official CLI tools.

trenchgun

Jira has official CLI as well https://appfire.atlassian.net/wiki/spaces/JCLI/overview

and plenty of unofficial ones

prakashn27

This is not an official API, this is from third party. stop promoting appfire products as official api.

tecleandor

Maybe something like wtfutil? (Although wtf development has been stuck for a year, but I guess that's the general idea...)

https://wtfutil.com/

buremba

HN

Atuin Desktop: Runbooks That Run

Atuin Desktop: Runbooks That Run