Skip to main content

How startup scripts run

A startup script runs once, when your machine is ready, so tools and models are in place before you log in.

On this page

A startup script is a shell script you attach to a reservation. It runs on the machine when the machine is ready, so the slow parts — installing packages, downloading a model — are done or under way by the time you log in. It's optional: without one, you get a clean machine.

When and how it runs

  • Once, at the start of the reservation, as soon as the machine is ready. It doesn't run again, even if you reconnect.
  • As your login user, in your home directory: the same user you connect as over SSH.
  • With a time limit of one hour. A script still running after an hour is stopped. That's plenty for installing tools and downloading most models; keep anything longer for your own session (see below).
  • With bash, unless the first line names another interpreter, such as #!/usr/bin/env python3.

You can log in while the script is still running. It won't stop when you connect or disconnect, and whatever it downloads keeps arriving in the background.

Adding a script to a reservation

On the reservation page (for plans that run startup scripts), Startup script lets you:

  • start from one of your saved scripts or one of the plan's recommended templates,
  • edit it in the text box — your changes apply to this reservation only, and
  • type a script from scratch, without choosing one.

Only the text in the box is saved with the reservation. If you later change or delete the saved script you started from, the reservation keeps the version you booked with.

Choose + New script to save a script to Startup Scripts in your dashboard; you come back to the reservation page with the new script in the text box.

Limits

  • At most 64 KB of text — plenty for a script; download large files from within it instead of pasting them in.
  • Line endings are converted to Unix style (\n), so a script written on Windows still runs.
  • Scripts are stored with your reservation, so don't put secrets in them — see Keeping secrets out of scripts.

Writing a good startup script

Start with these two lines, which our templates use too:

bash
#!/bin/bash
set -euo pipefail

set -euo pipefail stops the script at the first failing command instead of carrying on in a broken state.

A few more tips:

  • Make it safe to run on a clean machine. Each reservation starts from a freshly wiped machine: nothing from a previous reservation is there.
  • Print what it's doing with echo, so you can follow along.
  • Install into your home directory, for example Python packages in a virtual environment (python3 -m venv ~/.venvs/work).
  • Don't start long-running servers from it; start them yourself after logging in, inside tmux or screen (Connecting shows how).
  • Keep downloads within the hour. A 16 GB model downloads well inside an hour on a fast connection; a 65 GB one may not. Choose a 4-bit or 8-bit build to download less.

Checking on it

Log in and look at what it's done: the files it wrote, and whether its processes are still running (ps -u "$USER" lists yours).