hort up

Build a sandbox and open a session in it.

hort up [OPTIONS] <NAME>

Arguments:
  <NAME>  The sandbox to build, which is also the branch it creates

Options:
      --branch <BRANCH>  Check out this existing branch instead of creating one named after the sandbox
      --git <GIT>        How the sandbox gets git into `/workdir`, overriding what the configuration declares: `worktree` or `clone`
  -d, --detach           Return to the prompt with the sandbox running instead of opening a session in it
  -h, --help             Print help

Examples

cd ~/src/webapp
hort up fix-login                      # new branch fix-login from HEAD, then a shell inside
hort up fix-login -d                   # same, but return to your prompt
hort up review --branch feature/search # build on an existing branch
hort up ship-it --git clone            # give the box its own clone, so git works inside

What it does

1. Reads the configuration (global, then project; see Configuration). On a terminal with no global configuration yet, it first runs the hort config dialogue.
2. Checks that there is a project here: the nearest directory up from where you are that holds .hort.json, .devcontainer/devcontainer.json or .git.
3. Checks the host and the rootfs, in this order: user namespaces, pasta, git, ip (only for an egress allowlist), then the rootfs: configured, present, has /bin/sh, has the configured shell, has a world-writable /workdir.
4. Checks the rest of the configuration that can be wrong: resource sizes, databases sharing a port, and caches aimed inside read-only mounts.
5. Takes a per-name lock, so two hort up of the same name cannot race.
6. Decides what to build. A sandbox of that name that is already fully running is refused. One that is half-built (an orphan, or a live box whose networking is gone) is completed instead of refused.
7. Prepares /workdir: in a git repository, a new branch <name> from HEAD (or the --branch you named) checked out at ~/.local/state/hort/sandboxes/<name>/worktree-<name>, as a worktree or, in clone mode, as a clone of the repository. Without git, the project folder itself.
8. Records the sandbox on disk, before anything starts, so an interruption from here on leaves something hort ls can see.
9. Starts the container with its anchor process, then its networking (pasta; the egress proxy for an allowlist; database forwarders).
10. Starts the notification watcher, if an agent declares notify.stopHook. If that fails, it warns and carries on.
11. Opens a session, unless -d: exactly what hort attach <name> does.

If starting the container or its networking fails after the container is up, up undoes what it started (helpers, then container) and keeps the worktree and the record. The sandbox then shows as orphaned, and running hort up <name> again retries.

hort up <name> without -d behaves exactly like hort up <name> -d followed by hort attach <name>, including its exit status.

Building on a branch a down kept

hort down keeps the sandbox's branch. When you run hort up <name> and a branch <name> already exists and is not checked out anywhere, hort asks on a terminal:

branch 'fix-login' already exists (a 'hort down' keeps a sandbox's branch) — build sandbox 'fix-login' on it? [Y/n]

Enter (yes) builds the sandbox on that branch, exactly like --branch fix-login. Answering no, or running without a terminal, refuses with the ready command:

branch 'fix-login' already exists (a 'hort down' keeps a sandbox's branch) — run 'hort up fix-login --branch fix-login' to build the sandbox on it, or choose another name

Resuming a half-built sandbox

If a sandbox of that name is orphaned (its container died, for example after a reboot), hort up <name> builds a new container over the same worktree, with your uncommitted work intact, on whatever branch the worktree currently holds. If it is live but its networking is gone, hort up <name> restarts the networking without touching the container or the sessions inside. Neither prints anything on success.

Messages

Refusals before anything is built

Refusals about the name and the branch

Failures while building

Warnings (the sandbox still starts)

When a session opens (without -d), the warnings of hort attach can follow.