Skip to main content

How startup scripts run

A startup script runs once, as renter, when your machine is ready: the one-hour and 64 KB limits, ~/startup.log, checking its state and running it again.

On this page

A startup script is a shell script you attach to a reservation. It runs on the machine when the reservation starts, 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, automatically, at the start of the reservation: when your account is set up, after the machine's restart. It doesn't run again, even if you reconnect.
  • As renter, the same standard account you connect as over SSH. It never runs as root, so it can't use sudo.
  • In your home folder, with a login environment, so the same PATH you get when you log in (including Homebrew's tools on a Mac).
  • With bash, unless the first line names another interpreter, such as #!/usr/bin/env python3.
  • 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.

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.
  • At most one hour of running time.
  • Line endings are converted to Unix style (\n), so a script written on Windows still runs.
  • Scripts are stored with your reservation, so be careful with secrets in them — see Keeping secrets out of scripts.

DGX Spark and Mac Studio differ

  • On a DGX Spark, the one-hour limit stops everything the script started, including processes it left running in the background. The script also counts towards the memory limit on all your processes.
  • On a Mac Studio, the limit stops the script itself. A process that deliberately detaches itself (with setsid, or nohup … & and disown) can outlive the hour. It still runs only as you, and it ends with the rental.

The output: ~/startup.log

What the script prints goes to ~/startup.log in your home folder. The file starts with a line like:

text
=== Startup script started <time> ===

Follow it live after you log in:

bash
tail -f ~/startup.log

Checking its state

The state file says where the script is:

bash
cat /usr/local/var/renter-startup/state

It prints one of:

StateWhat it means
waiting for first startThe script hasn't started yet.
running since …It's running now.
exited (code 0) at …It finished. A code other than 0 means it failed; see the log.
stopped: one-hour limit reached at …It was still running after an hour and was stopped.
stopped: memory limit reachedOn a DGX Spark only: your processes reached the memory limit.

Running it again by hand

The machine keeps a readable copy of your script at /usr/local/var/renter-startup/startup. To run it again — after fixing whatever made it fail, for example — run:

bash
bash /usr/local/var/renter-startup/startup

It runs in your terminal, as you, and prints to the screen rather than to ~/startup.log. For a script in another language, run the copy with its interpreter instead. Run long jobs inside tmux or screen, so they carry on if your connection drops.

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 erased machine: nothing from a previous reservation is there.
  • Print what it's doing with echo, so you can follow along in ~/startup.log.
  • Install into your home folder, for example Python packages in a virtual environment (python3 -m venv ~/.venvs/work). There's no sudo, and brew install doesn't work on a Mac Studio.
  • Don't start long-running servers from it; start them yourself after logging in, inside tmux or screen. On a DGX Spark, anything the script starts is stopped at the one-hour limit anyway.
  • 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.