Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Commands

CommandWhat it doesChanges anything
hort up <name>Build a sandbox (or finish a half-built one) and open a session in it.yes
hort attach <name>Open another session in a running sandbox.records the attach time
hort run <name> -- <cmd>Run one command in a running sandbox with no terminal, exiting with its status.records the attach time
hort lsList every sandbox with its state, sessions, age, idle time, git mode, branch and dirty state.no
hort down <name>Tear a sandbox down: processes, container, worktree, record.yes
hort pruneRemove debris and, if asked, idle sandboxes, after confirming.yes
hort configAnswer a few questions and write the global configuration.writes ~/.config/hort/config.json
hort doctorReport what this host can do.no

hort help and hort <command> --help print the built-in help. There is no --version flag.

Exit status

  • 0: the command succeeded.
  • 1: hort refused or failed; the reason is printed on stderr as one line.
  • For hort up without -d, hort attach and hort run, once the session has opened: the exit status of the session, or 128 + signal if it was killed by a signal. A shell you leave with exit 3 makes hort exit with 3.
  • hort doctor: 1 when a hard requirement of the host is missing, even though the report is printed.

Output

Lists and reports (ls, prune, doctor) go to stdout. Errors and warning: lines go to stderr. Warnings never stop a command; they tell you something runs degraded.

Errors any command can print

Messages below that end in a detail come from the system and say what failed.

MessageMeaningWhat to do
invalid nameA sandbox name was empty or contained /, or an egress.allow entry is not a plain host name.Pick a name without /; write allowlist entries as example.com or *.example.com.
state directory error: ...hort could not read or write its own files under ~/.local/state/hort or determine your home directory.Check permissions and free space on that path.
working directory failed: ...The directory you ran hort from could not be read (for example it was deleted).cd somewhere that exists.
corrupt metadata: ...A sandbox record on disk cannot be read.hort prune offers to remove corrupt records.
git command failed: <operation>: <git's message>A git operation hort ran failed; git's own message follows.Read git's message; run the same operation yourself in the repository to see more.
container runtime failed: ...Building, joining or removing a container failed.See Troubleshooting.
sandbox networking failed: ...Starting or stopping pasta, the proxy or a database forwarder failed.See Troubleshooting.