restart_application #

View this page as Markdown

On this page

Generated automatically from the published contract sources.

A script calls this action over HTTPS at POST https://tzcloud.turnzero.ai/v1/restart_application, with a bearer credential and the action's payload as the JSON body. An MCP connection lists this action as the tool tzcloud_restart_application.

OAuth access tokens and minted tokens, including the turnzero command's computer token, are bearer credentials. The action determines which kinds, scopes and grants it accepts (Sign-in, sessions, and tokens).

Build metadata: Registered in this build. Registration describes the default dispatcher in this build. It does not guarantee that a caller has the required credential or grant, that a tool is listed for that connection, or that the required service is configured.

Contract description #

Restart one environment's running copy. It re-applies the bindings its serving version recorded, not the current manifest's. Each binding reads its secret's current value. The database keeps its data and password. Stored files stay as they are. No build or new version is made, and no daily deploy is spent. A new manifest binding needs a deploy or promote. Resume a halted environment first. Wait for any deploy, promote or restart in flight to end.

An answer not from this platform does not show whether the restart started. Examples are gateway error pages or closed connections. Call read_status with wait_seconds first. The restart started if the environment's deploy member under environments shows kind restart with a started_at later than your call. Repeat restart_application only if that read shows it did not start.

More about this action #

The platform re-creates the serving compute from the version it already serves, with no build and no new version. The restart applies the settings the platform has now, such as the new hostname after a rename. A binding the manifest added since that version takes effect at the next deploy or promote.

With wait_seconds, the call waits to reply until the restart ends. Without it, the call returns 202 at once with the state deploying and next, and the restart finishes in the background. Read its end with read_status or list_versions. A restart does not count against the application's deploys per day.

The wait_seconds argument: optional, a whole number of seconds from 1 to 45, counted from the call's arrival. The call waits for the version-history row it started, and replies when that row ends or the seconds pass. Each server holds one wait per application. This call's wait takes that place. A concurrent held read_status for that application on the same server returns at once, from its own read. A value outside 1 to 45 is refused invalid_request, and its detail gives 45 as the bound.

An environment never deployed is refused environment_never_deployed; deploy or promote to it first. deploy_in_flight means a deploy, promote or restart is running: read read_status with wait_seconds until it ends, then restart only if still needed. A halted environment is refused target_environment_halted; use halt_environment with resume: true, which starts the compute the halt stopped. You may need no restart after that resume.

Access and action metadata #

{
  "name": "restart_application",
  "resource": "environment",
  "tier": "reversible",
  "surface": "tzcloud",
  "addresses": [
    "tzcloud"
  ],
  "clients": [
    "bearer",
    "browser_session"
  ],
  "product": "cloud",
  "summary": "Restart one environment's running copy, re-applying the bindings its serving version recorded, each reading its secret's current value; a binding the manifest added since takes effect at the next deploy or promote. The platform re-creates its serving compute from the version it already serves, under the settings the platform holds now, the application's current hostname among them, with no build and no new version. It replies at once with the state `deploying` and `next`, and completes detached, read to its end through `read_status` and `list_versions`. With `wait_seconds` up to 45 it holds its answer until the restart ends. A restart spends none of the application's deploys per day, and it is refused `deploy_in_flight` while any deploy, promote, or restart of the environment is in flight.\n\nAn answer that is not this platform's own, such as a gateway's error page or a closed connection, says nothing about whether the restart was made. Read `read_status` with `wait_seconds` first: the restart started where the environment's deploy member under `environments` shows the kind `restart` with a `started_at` later than your call. Call `restart_application` again only where that read shows it did not start. Under the super_admin grant the call also takes `placement`, `standing` or `rule`, over any account's application. `rule` runs the placement rule once for the application's size and sleep setting. This operator act moves an existing `shared-0.5gb` production environment onto the shared grain.",
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": true,
    "openWorldHint": true
  }
}

MCP catalog entry #

{
  "name": "restart_application",
  "title": "Restart application",
  "tier": "reversible",
  "scenario": "CHI-L0-07",
  "summary": "Restart one environment's running copy. It re-applies the bindings its serving version recorded, not the current manifest's. Each binding reads its secret's current value. The database keeps its data and password. Stored files stay as they are. No build or new version is made, and no daily deploy is spent. A new manifest binding needs a deploy or promote. Resume a halted environment first. Wait for any deploy, promote or restart in flight to end.\n\nAn answer not from this platform does not show whether the restart started. Examples are gateway error pages or closed connections. Call `read_status` with `wait_seconds` first. The restart started if the environment's deploy member under `environments` shows kind `restart` with a `started_at` later than your call. Repeat `restart_application` only if that read shows it did not start.",
  "owners": [
    "PLD-L0-84",
    "PLD-L0-63",
    "MAPI-04"
  ]
}

request #

JSON pointer Description and constraints
"" (root) Type: object
Required fields: ["application","environment"]
/properties/application Your account's application id from list_applications, not its name or label.

Type: string
/properties/environment The environment whose running copy is restarted, development or production. It must hold a serving version with compute; an environment never deployed is refused environment_never_deployed.

Type: string
Pattern: ^(development|production)$
/properties/wait_seconds The seconds the answer is held until this call's version-history row ends. A value out of range is refused invalid_request.

Type: integer
Minimum: 1
Maximum: 45
/properties/placement Super-admin only, for any account's application. standing (default) re-creates compute in place. rule runs the placement rule once for its size and sleep setting, moving a standing shared-0.5gb production environment to shared compute. Other callers passing it are refused invalid_request.

Type: string
Allowed values: ["standing","rule"]

response #

JSON pointer Description and constraints
"" (root) Returns 202 at once with next where the request carries no wait_seconds: the restart's history row, of kind restart, is inserted and the work continues detached; its end is read through read_status and list_versions, never through the action record. With wait_seconds, the answer is held until the row ends: settled, it is 200 with the state deployed or failed and the row's outcome; unsettled, it is 202 with next.

Type: object
Required fields: ["contract_version","application","environment","version","state","hostname"]
/properties/contract_version Required value: 1
/properties/reference The short reference the platform recorded your call under: ten lowercase hexadecimal characters, the value in the call’s record row. Quote it when you report the call.

Type: string
Pattern: ^[0-9a-f]{10}$
/properties/summary The answer's first member: one sentence giving the environment's state and serving version and, for the row this call started, its version, kind, step, and seconds since it started, or how it ended.

Type: string
/properties/application Type: string
/properties/environment Type: string
Pattern: ^(development|production)$
/properties/version The number of the version the environment serves, which the restart re-creates; a restart allocates no new number.

Type: integer
/properties/state deploying on the 202 answer, which precedes the row's end. The state is deployed or failed on the 200 answer, where the request's wait_seconds saw the row end.

Type: string
Pattern: ^(deploying|deployed|failed)$
/properties/hostname The environment's hostname under the application's current label, the value the re-created copy reads as its public host.

Type: string
/properties/health_path The recorded manifest's health path, which the health gate that follows this act will probe, cut at 256 characters as the gate's record keeps it. It is absent only where the recorded manifest holds no health path, which the manifest's schema admits nowhere, and on the operator's restart of another account's application.

Type: string
/properties/settled Present where the request carried wait_seconds. True where the one read after the wait found the row this call started ended, whatever ended the wait. False means that read found the row still deploying, or could not read it, and not that it failed: next gives the call that waits on it.

Type: boolean
/properties/waited_ms Present where the request carried wait_seconds: the milliseconds the answer was held after the row started.

Type: integer
Minimum: 0
/properties/outcome Present where the wait settled: the row's outcome as list_versions returns it, cut where the operator restarts another account's application. Its result is succeeded on a deployed row and failed, interrupted, or superseded on a failed one.

Type: object
/properties/next Present where the answer is 202 with the state deploying: at once without wait_seconds, and where the wait did not settle. It is the exact call that reads the row to its end, read_status for the environment restarted, with wait_seconds 45.

Type: object
Required fields: ["action","arguments"]
Additional properties: false
/properties/next/properties/action Required value: read_status
/properties/next/properties/arguments Type: object
Required fields: ["application","environment","wait_seconds"]
Additional properties: false
/properties/next/properties/arguments/properties/application Type: string
/properties/next/properties/arguments/properties/environment Allowed values: ["development","production"]
/properties/next/properties/arguments/properties/wait_seconds Required value: 45
/properties/detail With the state deploying, says how the restart's step and end are read: the next call, read_status with wait_seconds 45, or a read every ten seconds.

With deployed or failed, says how the row ended. For a deployed run that entered health_gate, it says the check requested the health path alone, with no smoke path requested. It says to request the other routes, read read_status's server_errors, and read read_logs for errors. That form also says the new copy took each bound setting's current stored value.

With deployed and a run that entered no health_gate, it says no health check or smoke check ran and to request its pages or routes and read read_logs for errors. A row with no step list uses the health-check form.

Type: string

Complete payload contract #

{
  "request": {
    "type": "object",
    "required": [
      "application",
      "environment"
    ],
    "properties": {
      "application": {
        "type": "string",
        "description": "Your account's application `id` from `list_applications`, not its name or label."
      },
      "environment": {
        "type": "string",
        "pattern": "^(development|production)$",
        "description": "The environment whose running copy is restarted, `development` or `production`. It must hold a serving version with compute; an environment never deployed is refused `environment_never_deployed`."
      },
      "wait_seconds": {
        "type": "integer",
        "minimum": 1,
        "maximum": 45,
        "description": "The seconds the answer is held until this call's version-history row ends. A value out of range is refused `invalid_request`."
      },
      "placement": {
        "type": "string",
        "enum": [
          "standing",
          "rule"
        ],
        "description": "Super-admin only, for any account's application. `standing` (default) re-creates compute in place. `rule` runs the placement rule once for its size and sleep setting, moving a standing `shared-0.5gb` production environment to shared compute. Other callers passing it are refused `invalid_request`."
      }
    }
  },
  "response": {
    "type": "object",
    "required": [
      "contract_version",
      "application",
      "environment",
      "version",
      "state",
      "hostname"
    ],
    "properties": {
      "contract_version": {
        "const": 1
      },
      "reference": {
        "type": "string",
        "pattern": "^[0-9a-f]{10}$",
        "description": "The short reference the platform recorded your call under: ten lowercase hexadecimal characters, the value in the call’s record row. Quote it when you report the call."
      },
      "summary": {
        "type": "string",
        "description": "The answer's first member: one sentence giving the environment's state and serving version and, for the row this call started, its version, kind, step, and seconds since it started, or how it ended (PLD-L0-63)."
      },
      "application": {
        "type": "string"
      },
      "environment": {
        "type": "string",
        "pattern": "^(development|production)$"
      },
      "version": {
        "type": "integer",
        "description": "The number of the version the environment serves, which the restart re-creates; a restart allocates no new number."
      },
      "state": {
        "type": "string",
        "pattern": "^(deploying|deployed|failed)$",
        "description": "`deploying` on the 202 answer, which precedes the row's end. The state is `deployed` or `failed` on the 200 answer, where the request's `wait_seconds` saw the row end."
      },
      "hostname": {
        "type": "string",
        "description": "The environment's hostname under the application's current label, the value the re-created copy reads as its public host."
      },
      "health_path": {
        "type": "string",
        "description": "The recorded manifest's health path, which the health gate that follows this act will probe, cut at 256 characters as the gate's record keeps it. It is absent only where the recorded manifest holds no health path, which the manifest's schema admits nowhere (PLD-L0-63), and on the operator's restart of another account's application (MAPI-20)."
      },
      "settled": {
        "type": "boolean",
        "description": "Present where the request carried `wait_seconds`. True where the one read after the wait found the row this call started ended, whatever ended the wait. False means that read found the row still deploying, or could not read it, and not that it failed: `next` gives the call that waits on it (MAPI-04; PLD-L0-63)."
      },
      "waited_ms": {
        "type": "integer",
        "minimum": 0,
        "description": "Present where the request carried `wait_seconds`: the milliseconds the answer was held after the row started."
      },
      "outcome": {
        "type": "object",
        "description": "Present where the wait settled: the row's `outcome` as `list_versions` returns it, cut where the operator restarts another account's application. Its `result` is `succeeded` on a deployed row and `failed`, `interrupted`, or `superseded` on a failed one (PLD-L0-63)."
      },
      "next": {
        "type": "object",
        "required": [
          "action",
          "arguments"
        ],
        "properties": {
          "action": {
            "const": "read_status"
          },
          "arguments": {
            "type": "object",
            "required": [
              "application",
              "environment",
              "wait_seconds"
            ],
            "properties": {
              "application": {
                "type": "string"
              },
              "environment": {
                "enum": [
                  "development",
                  "production"
                ]
              },
              "wait_seconds": {
                "const": 45
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false,
        "description": "Present where the answer is 202 with the state `deploying`: at once without `wait_seconds`, and where the wait did not settle. It is the exact call that reads the row to its end, `read_status` for the environment restarted, with `wait_seconds` 45."
      },
      "detail": {
        "type": "string",
        "description": "With the state `deploying`, says how the restart's step and end are read: the `next` call, `read_status` with `wait_seconds` 45, or a read every ten seconds (MAPI-04).\n\nWith `deployed` or `failed`, says how the row ended. For a deployed run that entered `health_gate`, it says the check requested the health path alone, with no smoke path requested. It says to request the other routes, read `read_status`'s `server_errors`, and read `read_logs` for errors. That form also says the new copy took each bound setting's current stored value (PLD-L0-84).\n\nWith `deployed` and a run that entered no `health_gate`, it says no health check or smoke check ran and to request its pages or routes and read `read_logs` for errors. A row with no step list uses the health-check form."
      }
    },
    "description": "Returns 202 at once with `next` where the request carries no `wait_seconds`: the restart's history row, of kind `restart`, is inserted and the work continues detached; its end is read through `read_status` and `list_versions`, never through the action record. With `wait_seconds`, the answer is held until the row ends: settled, it is 200 with the state `deployed` or `failed` and the row's `outcome`; unsettled, it is 202 with `next` (MAPI-04; PLD-L0-84)."
  }
}

Shared contracts #