--- title: "How do scripts work?" url: "https://ploi.io/documentation/server/how-do-scripts-work" published: "2026-09-29" last_updated: "2026-09-29" --- # How do scripts work? Scripts are bash scripts you save once in Ploi and run on one or more of your servers. You can start them by hand, on a schedule, or when a server boots or shuts down. Scripts are part of every paid plan. Running them on a schedule needs the Pro or Unlimited plan, running them on boot or shutdown needs the Unlimited plan. ### Creating a script Click **Scripts** in the sidebar, then **Create script**. Give the script a label, choose the user it runs as and write the script in the editor. The user is `ploi` or `root`. Be careful with root, a mistake in a root script can break the server. - A script can be up to 7,500 characters. - Nobody is there to answer prompts, so every command has to run without asking for input. Ploi won't save a script with an `apt install`, `apt update` or `apt upgrade` line that lacks `-y`. Other commands that wait for input make the script hang until it times out. - Ploi runs the script with bash, so a shebang line has no effect. - There are no placeholders. Ploi runs the script exactly as you wrote it. Scripts belong to your account. In a team you see your own scripts and run them on the servers of the team you are working in. Tick **Use this script as default deploy script for new sites** to make a script the deploy script of every site you install a repository on from then on. ### Running a script Click **Run** next to the script, select the servers and click **Run script**. The output of each server streams live on that page. Ploi uploads the script over SSH, runs it and deletes the file afterwards. - A run can take up to 200 seconds. Work that takes longer belongs in a daemon or a [cron job](/documentation/server/how-do-i-create-a-cron-job) on the server. - Starting the same script on the same server again within a minute does nothing, so a double click doesn't run it twice. - Every run leaves an entry with the output in the server's **Logs**. When the script exits with an error, the entry says "Script <label> exited with status" followed by the exit code. - Ploi doesn't send an e-mail or notification when a script fails. Check the server logs. ### Running a script on a schedule Click **Schedule** next to the script. Enter a cron expression or pick a preset such as **Every hour** or **Daily at 03:00**, select the servers and click **Add schedule**. A script can have more than one schedule. Cron expressions run in UTC. `0 3 * * *` runs at 03:00 UTC, which is 05:00 in Amsterdam during summer time. The **Next run** and **Last run** times in the list are shown in your browser's timezone. The schedules run from Ploi, which connects to the server over SSH at each moment. Ploi skips servers that aren't active. When Ploi misses a moment, it runs the script once within the next ten minutes, never several times in a row to catch up. You can pause, resume, edit and delete each schedule. The results show up in the server logs, like a manual run. A task that has to run even when Ploi can't reach the server is better off as a [cron job](/documentation/server/how-do-i-create-a-cron-job) on the server itself. ### Running a script when a server boots or shuts down Actions run a script when something happens on a server. There are two triggers, **Server has booted** and **Server is shutting down**. Click **Actions** next to the script, pick the trigger and the servers, set a delay if you need one and click **Add action**. Ploi installs a small systemd unit on each selected server. When the trigger fires, the unit lets Ploi know, and Ploi runs the script over SSH after the delay. The list shows per server whether the unit is installed. When Ploi can't reach a server, the status says **Failed**. Hover over it to see why. - The boot trigger waits until the network and SSH are up. When your script depends on other services, such as MySQL or a queue worker, add a delay so they have time to start. The delay can be up to two hours. - The shutdown trigger only fires on a clean shutdown. A hard reset or power loss skips it. Ploi runs the script after the server has reported the shutdown, so the server may already be gone by then. Keep shutdown scripts short and don't give them a delay. - A paused action keeps its unit on the server, but Ploi ignores the trigger. - A script with actions can't be deleted. Delete its actions first, Ploi then removes the systemd units from the servers. ### API Scripts, schedules and actions are also available in the API, which can also run a one-off script on a server without saving it first. See the [scripts API documentation](https://developers.ploi.io/scripts/run-one-off-script).