@@ 0,0 1,23 @@
+ ---
+ title: SSH access to build VMs
+ ---
+ 
+ You can interact directly with your builds by connecting to the runner over SSH.
+ This is helpful for troubleshooting your manifests, or just getting a quick
+ temporary environment to test something in.
+ 
+ When a build fails, the VM stays alive for an extra ten minutes, and you'll be
+ presented with instructions on how to connect to the runner via SSH, e.g.:
+ 
+ ```
+ $ ssh -t builds@azusa.runners.sr.ht connect 81809
+ Connected to build job #81809 (failed):
+ https://builds.sr.ht/jobs/~sircmpwn/81809
+ Your VM will be terminated 4 hours from now, or when you log out.
+ 
+ bash-5.0 $
+ ```
+ 
+ In addition to connecting to failed builds over SSH, you can add `shell: true`
+ to your [manifest](manifest.md) to always enable SSH access. Then, you'll be
+ able to interact with your build as it runs.

@@ 57,6 57,15 @@ specific format varies by base image, [consult the compatibility
  page](/builds.sr.ht/compatibility.md) for details.
  
+ ## shell
+ 
+ *boolean*
+ 
+ Whether to keep the build VM alive after all of the tasks have finished, even if
+ it doesn't fail, so you can SSH in. You can also SSH in before the tasks have
+ finished and tail the output of the build in your terminal. [Learn more about
+ SSH access to build VMs](build-ssh.md).
+ 
  ## sources
  
  *list* (of *string*)