Skip to main content
This walkthrough uses sh, a recipe dabs ships with: a shell in a clean box with your current directory live-mounted at /work. Run everything from your project directory.
Screens below are verified by tests/test_quickstart.py. Generated names (like sh-a3f9c21d) are blanked to ________ — yours will differ. The :done line is the test harness’s end marker, kept for fidelity.

​
1. Boot a box

--detach boots a fresh box and leaves it up without running the recipe’s command. Note the id it prints — that is your handle for everything else. 
dabs recipe sh --detach

✓ recipe booted: sh
id: sh-________
instance: shell-____________
(no command was run — the recipe's command is not started by `--no-command`)
reap: dabs rm sh-________
run recipe command: dabs exec sh-________ -- sh
Every boot is a new, pristine box. Booting again gives you a second box; it never reuses the first.

​
2. Reach in with exec

dabs exec <box> '<shell line>' runs a shell command inside the box. Your project is at /work, mounted live: 
dabs exec sh-________ 'cat /work/note.txt && echo boxed >> /work/note.txt'

hello from my project
Because sh uses a live mount, the box’s write is now on your disk: 
cat note.txt

hello from my project
boxed
If you don’t want the box writing to your files, use a recipe with a copy: source instead — see Sources.

​
3. See what dabs owns

dabs ls

local (bwrap, this machine)
  NODE             KIND     VOL  HELD  TMP  STATE  WHERE
  myproj-________  project                         ~/myproj
  └─ sh-________   box                      live   ~/.dabs/nodes/sh-________  (shell-____________)
The tree reads: a project node marks the directory you ran from, and the box stands on it. live means the box is running right now.

​
4. Reap it

dabs rm never tears a box down silently. Without -y it previews what it would take and asks — on a terminal, as an interactive dialog: 
dabs rm sh-________

╭────────────────────────────────────────────╮
│ Removing sh-________ reaps 1 node(s):      │
│   NODE         KIND  VOL  HELD  TMP  STATE │
│   sh-________  box                   live  │
│ Proceed?                                   │
╰────────────────────────────────────────────╯
┃ Proceed?
┃
┃   Yes     No
Answering No keeps everything (dabs: rm sh-________: kept). Pass -y to consent up front — the form agents and scripts use: 
dabs rm sh-________ -y

✓ shell-____________ stopped
✓ sh-________ removed

​
Where to next

  • Concepts — what nodes, places, and spaces actually are.
  • Recipes — write your own box in ten lines of YAML.
  • Worktrees — hand an agent a branch instead of your tree.