diff --git a/dictionary-octopus.txt b/dictionary-octopus.txt
index 8cca5bda76..37a922e362 100644
--- a/dictionary-octopus.txt
+++ b/dictionary-octopus.txt
@@ -157,6 +157,8 @@ emptytitle
enableservicemessages
entra
environmentids
+environmentstate
+environmenturl
eprintfn
esac
exfiltrate
diff --git a/public/docs/projects/ephemeral-environments/ephemeral-environment-url.png b/public/docs/projects/ephemeral-environments/ephemeral-environment-url.png
new file mode 100644
index 0000000000..4e8e4ce1b9
Binary files /dev/null and b/public/docs/projects/ephemeral-environments/ephemeral-environment-url.png differ
diff --git a/src/pages/docs/infrastructure/environments/environment-state.md b/src/pages/docs/infrastructure/environments/environment-state.md
new file mode 100644
index 0000000000..b1dea387f1
--- /dev/null
+++ b/src/pages/docs/infrastructure/environments/environment-state.md
@@ -0,0 +1,135 @@
+---
+layout: src/layouts/Default.astro
+pubDate: 2026-08-07
+modDate: 2026-08-08
+title: Environment state
+navTitle: Environment state
+description: Save key/value state during a deployment or runbook run, then read it back in later deployments and runs.
+navOrder: 30
+---
+
+Environment state lets a deployment or [runbook](/docs/runbooks) run save key/value pairs scoped to the combination of project, environment, and optionally a tenant. Later deployments and runbook runs for the same project and environment can then read those values back.
+
+Environment state is useful in scenarios where a value produced during one run needs to be reused later. A common example is provisioning and deprovisioning [ephemeral environments](/docs/infrastructure/ephemeral-environments). A provisioning runbook might create a Kubernetes namespace or an application URL that later deployments and the deprovisioning runbook depend on. Recording each value as environment state means Octopus stores it once, so every later run reads it directly instead of re-deriving the value.
+
+Each state entry is scoped to project, environment, and optionally a tenant, so state isn't shared with other projects, environments, or tenants. Setting an entry with a key that already exists for the same project, environment, and tenant overwrites the previous value.
+
+## Setting environment state
+
+Set state from a PowerShell or Bash [script step](/docs/deployments/custom-scripts) using the wrapper functions Octopus provides.
+
+
+PowerShell
+
+```powershell
+Set-EnvironmentState -Key "namespace" -Value "webstore-pr-482"
+```
+
+
+
+Bash
+
+```bash
+set_environmentstate "namespace" "webstore-pr-482"
+```
+
+
+
+### Sensitive values
+
+Mark a value as sensitive to store it encrypted at rest and mask it in task logs. Add the `-Sensitive` switch in PowerShell, or `-sensitive` as the third argument in Bash.
+
+
+PowerShell
+
+```powershell
+Set-EnvironmentState -Key "connectionString" -Value "Server=db;Password=s3cret" -Sensitive
+```
+
+
+
+Bash
+
+```bash
+set_environmentstate "connectionString" "Server=db;Password=s3cret" -sensitive
+```
+
+
+
+## Using environment state
+
+Octopus makes each state entry available as a [variable](/docs/projects/variables) named `Octopus.Environment.State[key]` in later deployment or runbook run, where `key` is the name you set.
+
+Read it from a script:
+
+
+PowerShell
+
+```powershell
+$namespace = $OctopusParameters["Octopus.Environment.State[namespace]"]
+```
+
+
+
+Bash
+
+```bash
+namespace=$(get_octopusvariable "Octopus.Environment.State[namespace]")
+```
+
+
+
+## Setting an environment URL
+
+An environment URL is a type of environment state, but gets first-class support in Octopus. It is stored like any other environment state, and surfaced as a clickable link in the Octopus Web Portal and available from the API.
+
+Set a URL with the `Set-EnvironmentUrl` (PowerShell) or `set_environmenturl` (Bash) function. The first argument is the key that names the URL, and the second is the URL itself.
+
+
+PowerShell
+
+```powershell
+Set-EnvironmentUrl -Key "Store front" -Url "https://pr-123.example.com"
+```
+
+
+
+Bash
+
+```bash
+set_environmenturl "Store front" "https://pr-123.example.com"
+```
+
+
+
+URLs set this way show as clickable links on the [Ephemeral Environments](/docs/projects/ephemeral-environments#environment-urls) in the project, so anyone reviewing the environment can open the running app.
+
+:::div{.hint}
+A URL is a special kind of environment state, the key used must be unique across all state entries (including other URLs) for the same project, environment, and tenant. Reusing a key overwrites the value stored under it.
+:::
+
+### Getting URLs from the API
+
+You can fetch the environment URLs from the API, which is useful for AI agents and scripts that need a link to the running app without reading the task log. Add an optional `tenantId` query parameter for [tenanted](/docs/tenants) runs.
+
+```text
+GET /api/spaces/{spaceId}/projects/{projectId}/environments/{environmentId}/urls
+```
+
+The response is an array of name and URL pairs:
+
+```json
+[
+ { "Name": "Store front", "Url": "https://pr-123.example.com" }
+]
+```
+
+## Availability
+
+Environment state is available on Octopus Cloud, and will be available to self-hosted customers from version `2026.3`.
+
+## Learn more
+
+- [Ephemeral environments](/docs/infrastructure/ephemeral-environments)
+- [Runbooks](/docs/runbooks)
+- [System variables](/docs/projects/variables/system-variables)
diff --git a/src/pages/docs/projects/ephemeral-environments/index.md b/src/pages/docs/projects/ephemeral-environments/index.md
index a6ce48f019..7108722308 100644
--- a/src/pages/docs/projects/ephemeral-environments/index.md
+++ b/src/pages/docs/projects/ephemeral-environments/index.md
@@ -1,7 +1,7 @@
---
layout: src/layouts/Default.astro
pubDate: 2025-10-17
-modDate: 2026-07-22
+modDate: 2026-08-10
title: Ephemeral Environments
navTitle: Ephemeral Environments
navSection: Ephemeral Environments
@@ -155,6 +155,21 @@ Environments can be filtered by name and by the current state of the environment
+## Environment URLs
+
+An environment URL is a type of [environment state](/docs/infrastructure/environments/environment-state) that Octopus has built-in support for. When an environment URL is set during a provisioning runbook or deployment, Octopus shows it as a clickable link in the table on the Ephemeral Environments page, making it easy to open the running application without needing to look through task logs. To set an environment URL from a deployment or runbook step, see [Setting an environment URL](/docs/infrastructure/environments/environment-state#setting-an-environment-url).
+
+For example, the following deployment script builds the running app's URL from the namespace it deployed to, and sets an environment URL named `App`:
+
+```powershell PowerShell
+$applicationUrl = "https://$namespace.australiaeast.cloudapp.azure.com"
+Set-EnvironmentUrl "App" "$applicationUrl"
+```
+
+Octopus then shows the `App` URL as a clickable link on the Ephemeral Environments page:
+
+
+
## Updating an existing environment
### Automatic Deployments
diff --git a/src/pages/docs/projects/variables/system-variables.md b/src/pages/docs/projects/variables/system-variables.md
index d2bfefef2f..d2665b3412 100644
--- a/src/pages/docs/projects/variables/system-variables.md
+++ b/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-07
title: System variables
sidebarLabel: System variables
navOrder: 20
@@ -130,6 +130,7 @@ Deployment-level variables are drawn from the project and release being deployed
| `Octopus.Environment.MachinesInRole[role]` | The machines with the specified target tag being deployed to. | `machines-123,machines-124` |
| `Octopus.Environment.Name` | The name of the environment. | Production |
| `Octopus.Environment.SortOrder` | The order applied to the environment on the dashboard and elsewhere. | `3` |
+| `Octopus.Environment.State[key]` | The value of an [environment state](/docs/infrastructure/environments/environment-state) entry with the given key. | `#{Octopus.Environment.State[appUrl]}` |
| `Octopus.Machine.Id` | The ID of the machine. | `machines-123` |
| `Octopus.Machine.Name` | The name used to register the machine in Octopus. Not the same as the hostname. | `WEBSVR01` |
| `Octopus.Machine.Roles` | The target tags associated with the machine. | `web-server,frontend` |