Startup scripts

How it works#

Startup scripts execute once, automatically, when a VM first boots. They run as root via the guest agent, so no SSH connection is required. Scripts have a 10-minute timeout, and their output is captured for debugging.

1. Select a script when creating a VM.
2. The VM boots and the OS installs.
3. The script runs automatically.

Edge script library#

Pre-built, tested scripts maintained by Edge. Available to all users out of the box.

Web servers and stacks#

Applications#

Development tools#

Security#

Using a script when creating a VM#

1. Navigate to Compute → Create VM.
2. Configure your VM as usual (region, OS, resources, SSH keys).
3. In the Startup Script section, select a script from the dropdown.
4. If the script has parameters, fill them in (passwords are auto-generated if left blank).
5. Click Create VM.

The script runs automatically once the VM finishes provisioning. You can check its status on the VM detail page.

Creating custom scripts#

Create your own scripts to automate any setup you need.

1. Go to Compute → Scripts.
2. Switch to the My Scripts tab.
3. Click Create Script.
4. Write your bash script and optionally define parameters.
5. Click Save. Your script is now available in the VM creation dropdown.

Script guidelines#

• Start with #!/bin/bash and set -e: exit on error so failures are caught and reported.
• Log progress with echo: output is captured and visible on the VM detail page.
• Use export DEBIAN_FRONTEND=noninteractive: prevents apt from prompting for input during package installation.
• Keep it under 10 minutes: scripts are killed after 10 minutes. For longer setups, have the script kick off a background task.

Parameters#

Use the ${param_name} syntax in your script. When the VM is created, parameter values are substituted before execution.

#!/bin/bash
set -e

DB_PASSWORD="${db_password:-$(openssl rand -base64 16)}"

echo "Setting up database with password: $DB_PASSWORD"
# ... your setup logic ...

The :-default syntax provides a fallback if the parameter is empty.

Checking execution status#

After creating a VM with a startup script, you can monitor its progress on the VM detail page.

• Pending: the VM is still provisioning and the script is queued
• Running: the script is executing inside the VM
• Completed: the script finished successfully
• Failed: the script encountered an error (click View output for details)

Managing scripts from the CLI#

The full script workflow is available in the Edge CLI. You can list the library, manage your custom scripts and attach a script when creating a VM.

# Browse available scripts (Edge library + your own)
edge compute scripts list

# Create a custom script from a file
edge compute scripts create --name "My Setup" --file setup.sh

# Run a script on a new VM, with parameters
edge compute create --name blog --size s-2vcpu-4gb --image ubuntu-24 \
    --region london --script wordpress \
    --script-param site_title="My Blog" \
    --script-param admin_email=me@example.com

See the CLI compute commands reference for all script commands.

API and agent access#

Startup scripts can also be used via the API and the AI agent.

Inline script (API/agent)#

Pass a script directly when creating a VM using the setup_script field:

POST /agent/compute/vms
{
  "name": "my-server",
  "size": "small",
  "setup_script": "#!/bin/bash\nset -e\napt update && apt install -y nginx"
}

Using a library script by ID (agent)#

Agents can list available scripts with GET /agent/compute/scripts and reference one by ID. Parameter substitution happens server-side:

POST /agent/deploy/app
{
  "project": "my-blog",
  "compute": {
    "size": "small",
    "script": "wordpress",
    "script_params": { "site_title": "My Blog", "admin_email": "me@example.com" }
  }
}

The same script / script_params fields work on POST /agent/compute/vms.

Checking status#

GET /api/compute/vms/{vm_id}/scripts

{
  "executions": [
    {
      "id": "...",
      "script_name": "setup_script",
      "status": "completed",
      "output": "=== Docker Installed ===\nDocker: Docker version 27.4...",
      "started_at": "2026-03-03T00:15:00Z",
      "completed_at": "2026-03-03T00:17:34Z"
    }
  ]
}

Troubleshooting#

Script shows “Failed”#

• Click View output on the VM detail page to see the error.
• Make sure your script starts with #!/bin/bash.
• Check that all package names are correct for the selected OS.
• Ensure DEBIAN_FRONTEND=noninteractive is set for apt commands.

Script still “Pending” after the VM is running#

Scripts are executed shortly after the VM reaches “running” status. Allow up to 30 seconds for the guest agent to initialise. If the status doesn’t change, the guest agent may not be available. Try restarting the VM.

Script timed out#

Scripts are killed after 10 minutes. If your setup takes longer, have the script start a background process and exit. For example, use nohup ./long-task.sh &.