2025 7 21 https://shelter.sirref.org/shelter-0003/ shelter-0003 /shelter-0003/ Getting Started After getting shelter installed, you can start by running the shelter command. If this is your first time running shelter then you will be guided to setting up some user information. To avoid having to run commands as root, shelter comes with a shelterd command for running a daemon environment. Users then communicate with this daemon using capnproto. References Context Backlinks The Shelter Developers 2025 7 21 https://shelter.sirref.org/index/ index /index/ Shelter Welcome to Shelter's documentation. Shelter is a metashell. A tool for managing shell sessions in a more reproducible way. To get started with Shelter, you can read the getting started tutorial. For a more thorough understanding of what Shelter offers and how to use it, then please follow the documentation. 2025 7 21 https://shelter.sirref.org/shelter-0001/ shelter-0001 /shelter-0001/ About Shelter's Documentation Shelter's documentation is written in using Forester via Graft. The main ethos is to divide the documentation into fairly small, standalone chunks. These can then be pieced together into documentation pages that are tightly linked. For reference documentation, we have: The Shelterfile syntax -- the syntax for shelterfiles, a mishmash of Dockerfiles and shell scripts. These are useful for setting up branches for developement The available meta-commands -- these extend past shell scripts and allow users to access the more interesting parts of Shelter like @ undo or @ merge <branch> for example. The development logs -- a set of developer logs about the activity on shelter. 2025 7 21 https://shelter.sirref.org/shelter-0002/ shelter-0002 /shelter-0002/ Shelter Meta-commands When developing inside Shelter, most commands are sent straight to a shell how to configure shelter To interact with the meta aspects of Shelter you can prefix your command with @. If you type just @ then you will get a list of possible commands. 2025 7 21 https://shelter.sirref.org/at-session/ at-session /at-session/ @ session Sessions are your primary way of controlling different environments. You can think of them as git branches pointing at specific instances of data and code. By default, you will start shelter in the main session. Sessions must have alpine This command will create a fresh session with no history called experiment-1 using the Debian base image. This is a similar command, but the name will be randomly generated and is ensured to be unique. It is a bit like having a Dockerfile with a FROM debian at the top. Will list all the currently available sessions. When no --image is specified, this will try to switch you into an existing session if one exists, otherwise it will create a new session based on the current session. 2025 7 21 https://shelter.sirref.org/at-undo/ at-undo /at-undo/ @ undo The @ undo command will move your session back one commit into the past. You may specify a number of commits to move, for example @ undo n to move back n commits. If there are less than n commits, we will stop going backwards. 2025 7 21 https://shelter.sirref.org/at-how/ at-how /at-how/ @ how The @ how <path> command allows you to ask Shelter to explain how a file came to be. Which executables wrote to the file, and what files did those executables read. This is an approximation to the provenance of a piece of data inside a Shelter session. 2025 7 21 https://shelter.sirref.org/at-import/ at-import /at-import/ @ import An experimental command for importing arbitrary URIs into Shelter. Shelter Programmers 2025 11 16 https://shelter.sirref.org/shelter-log-001/ shelter-log-001 /shelter-log-001/ Import statements Welcome to the first Shelter log! In this log I will explain the work I have been doing to add an @ import meta-command. The syntax thus far is relatively straightforward. ]]> There are a few key principles underlying @ import. It should be at least as expressive as Docker's COPY ... command. It should deal with a wider variety of import sources. In addition to local https:// archives over ssh etc. Imports, where possible, should be catalogued and shared across sessions. Shelter Programmers 2025 11 16 URIs as Sources branch already allows users to import local files and directories into their session. For example: By allowing arbitrary URIs in the import command, we hope to force users away from downloading data via curl or python scripts. Lifting these side-effectful imports into Shelter allows us to manage the data in a much cleaner fashion. Shelter Programmers 2025 11 16 Scripts as Sources One idea I had was to allow users to invoke scripts as there "import source". Something like: And using the same eBPF tracing we use during normal execution we can capture a fairly good idea of the tools and files needed to perform an import. Shelter Programmers 2025 11 16 Sharing Imports One example of better data management is that Shelter imports can be When a user imports some data, they can optionally name that piece of data. For example: Shelter stores that away and makes a link between the name, the URI and the underlying data. A user may then import the same piece of data into a different session by simply writing: intent via the naming scheme, it makes it possible to then version the data and have a means by which to update said data, one could imagine: Which will retry the original URI and see if the data has changed, or if it has not. There is an implicit versioning number that users can specify in the name should they choose to. Related 2025 7 21 https://shelter.sirref.org/shelter-0005/ shelter-0005 /shelter-0005/ Shelterd Shelter's daemon process and admin interface. Contributions