Document that C# script steps require the .NET SDK

src/pages/docs/deployments/custom-scripts/index.md

@@ -1,7 +1,7 @@
 ---
 layout: src/layouts/Default.astro
 pubDate: 2023-01-01
-modDate: 2025-05-19
+modDate: 2026-08-11
 title: Custom scripts
 description: Custom scripts allows you to script anything you want using PowerShell, Dotnet Script, F#, Python, or Bash.
 icon: fa-solid fa-file-code
@@ -32,6 +32,35 @@ Support for ScriptCS in Octopus will be removed from `2025.3`.
 To view previous and upcoming deprecations, please visit our [deprecations page](https://octopus.com/docs/deprecations).
 :::
 
+## C# script requirements {#csharp-requirements}
+
+C# scripts (`.csx`) run through [dotnet-script](https://github.com/dotnet-script/dotnet-script), which requires the **.NET SDK** on the machine that runs the script. The .NET runtime on its own is not enough. Depending on where the step runs, that machine is a [deployment target](/docs/infrastructure/deployment-targets), a [worker](/docs/infrastructure/workers), or the Octopus Server.
+
+The SDK is required for every C# script, including scripts that reference no NuGet packages. Before running your script, dotnet-script generates a project file for it and runs `dotnet restore` against that project, and `dotnet restore` is part of the SDK rather than the runtime.
+
+If only the runtime is installed, the step fails with a message that points at your NuGet references instead of the missing SDK:
+
+```text
+Unable to restore packages from '/root/.cache/dotnet-script/work/net8.0/script.csproj'
+Make sure that all script files contains valid NuGet references
+```
+
+The path and target framework in that message vary by machine. If you see it and your script has no NuGet references, the machine running the step is missing the .NET SDK.
+
+### Which version of the .NET SDK {#csharp-sdk-version}
+
+We don't tie C# scripts to a specific version of the SDK, because dotnet-script chooses the target framework itself at run time. It resolves a .NET runtime through the `dotnet` on the path, then generates a project targeting that runtime's version. The SDK on the machine must be able to build for that target framework, so install an SDK that is at least as new as the .NET runtime the machine will resolve. Installing the .NET SDK also installs a matching runtime, so one SDK install covers both.
+
+Calamari's own target framework has no bearing on this. Calamari is [self-contained](/docs/octopus-rest-api/calamari) and carries its own runtime, but your C# script is executed by the `dotnet` installed on the machine.
+
+The [octopusdeploy/worker-tools images](/docs/projects/steps/execution-containers-for-workers/#worker-tools-images) include a .NET SDK, so C# scripts run in an [execution container](/docs/projects/steps/execution-containers-for-workers) without any extra setup.
+
+### NuGet sources for C# scripts {#csharp-nuget-source}
+
+By default, dotnet-script restores packages from `https://api.nuget.org/v3/index.json`. To restore from a different feed, set the `Octopus.Action.Script.CSharp.NuGetSource` [system variable](/docs/projects/variables/system-variables) on the project or step.
+
+Only one source can be supplied, and the value replaces the default rather than adding to it. A script that needs packages from both nuget.org and a private feed can't be expressed with this variable today. Octopus always passes a single source to dotnet-script, and that source overrides any sources configured in a `NuGet.config` on the machine. If your script needs packages from more than one feed, point the variable at a feed that can serve all of them, such as a private feed configured to proxy nuget.org upstream.
+
 ## What you can do with custom scripts
 
 If an activity can be scripted, Octopus can run that script as a standalone activity or as part of a larger orchestration.

src/pages/docs/infrastructure/deployment-targets/linux/ssh-requirements.md

@@ -1,7 +1,7 @@
 ---
 layout: src/layouts/Default.astro
 pubDate: 2023-01-01
-modDate: 2024-03-22
+modDate: 2026-08-11
 title: SSH target requirements
 description: Requirements for using SSH deployment targets with Octopus.
 navOrder: 15
@@ -31,6 +31,20 @@ See the Bash Reference Manual, section [6.2 Bash Startup Files](http://www.gnu.o
 
 Since it is self-contained, .NET Core does not need to be installed on the target server. However, there are still some [pre-requisite dependencies](https://learn.microsoft.com/en-us/dotnet/core/install/linux-scripted-manual#dependencies) required for .NET Core itself that must be installed.
 
+This covers Calamari itself. Running [C# scripts](#csharp) on the target is a separate requirement.
+
+## C# scripts {#csharp}
+
+C# scripts (`.csx`) are executed by [dotnet-script](https://github.com/dotnet-script/dotnet-script), which requires the **.NET SDK** on the target, not just the .NET runtime. This applies to every C# script, including scripts that reference no NuGet packages.
+
+Octopus can execute C# scripts on SSH targets provided the following criteria are met:
+
+- The .NET SDK is installed
+- `dotnet` is on the path for the SSH user executing the deployment
+- The SDK is at least as new as the .NET runtime that `dotnet` resolves on the target
+
+See [C# script requirements](/docs/deployments/custom-scripts/#csharp-requirements) for the failure you'll see if only the runtime is installed.
+
 ## Git-based steps
 
 Git-based steps (steps that clone or fetch from a git repository as part of a deployment or runbook) require OpenSSL **1.1** or **3** on the host. SSH targets running with other OpenSSL versions will fail when running these steps.

src/pages/docs/projects/variables/system-variables.md

@@ -1,7 +1,7 @@
 ---
 layout: src/layouts/Default.astro
 pubDate: 2023-01-01
-modDate: 2026-08-03
+modDate: 2026-08-11
 title: System variables
 sidebarLabel: System variables
 navOrder: 20
@@ -239,7 +239,7 @@ You can also read these variables for a different action using indexed notation,
 | `Octopus.Action.Package.SkipIfAlreadyInstalled` | Whether re-deployment is skipped when the package version is already on the machine. | `False` |
 | `Octopus.Action.Script.ScriptBody` | The script being run in a script step. | `Write-Host 'Hello'` |
 | `Octopus.Action.Script.Syntax` | The syntax of the script being run in a script step. | PowerShell |
-| `Octopus.Action.Script.CSharp.NuGetSource` | The NuGet source used by the dotnet executor for C# script steps. | `https://my-nuget-server/nuget` |
+| `Octopus.Action.Script.CSharp.NuGetSource` | The NuGet source used by the dotnet executor for C# script steps. Only one source can be supplied, and it replaces the default source rather than adding to it. See [NuGet sources for C# scripts](/docs/deployments/custom-scripts/#csharp-nuget-source). | `https://my-nuget-server/nuget` |
 | `Octopus.Action.SkipRemainingConventions` | Set as an output variable to finish the action without running further conventions or scripts. | `True` |
 | `Octopus.Action.TargetRoles` | The machine target tags targeted by the action. | `web-server,frontend` |
 | `Octopus.Action.Template.Id` | The ID of the step template the action is based on, if any. | `action-templates-123` |