halt_environment #

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/halt_environment, with a bearer credential and the action's payload as the JSON body. An MCP connection lists this action as the tool tzcloud_halt_environment.

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 #

Halt your deployed environment without deleting its version, data, credentials or declarations, or resume with resume: true. While halted its hostname returns 503 environment_halted and schedules stop. Resume restarts schedules from that instant, without replaying missed runs. A deploy ends a development halt. Halted production refuses deploys, promotes, rollbacks and restarts until resumed. Halting production during its deploy's image build ends that deploy. After the build, deploy_in_flight refuses the halt. The account owner must have requested or agreed to this production halt. Development needs no ask. A resume needed for that agreed promote or roll back is part of the same request.

More about this action #

A halt stops production's compute. A container app stops during the call. A pod's scaler is paused at zero replicas within about 11 seconds after the call returns. A halted development environment serves nothing. Its compute stops when idle at the latest, for either size.

The environment argument: development or production. A halt of production is an account action. It is accepted under the account's session, or under a minted token scoped to the whole account. Under a minted token bounded to one application, it is refused 403 account_credential_required, so that a leaked application token cannot stop production. A halt of development, and halt_environment with resume: true, are accepted under either token.

A halt is refused deploy_in_flight while a deploy, promote, or restart of the environment is in progress, with one exception. A halt of production while a production deploy is still building its image is accepted, and it ends that deploy. Once that deploy is past its build, the halt is refused until the deploy ends.

A halt of an environment with no deployed version is refused environment_never_deployed. A halt of an environment that is already halted returns its current state with the outcome unchanged.

End a halt: the hostname responds again, every schedule of the environment restarts from the resume time, no run due during the halt is replayed, and the compute the halt stopped is started. A resume starts production's compute.

If the pod's scaler is missing, the resume ends the halt and restarts the schedules from the resume time. The resume starts no compute. The response's detail reports the missing scaler, and the platform logs a warning for its operator. Call read_status to check the environment. If serving compute needs to be restored, use restart_application to recreate it and its scaler. A development environment of either size starts on its next request. A resume of an environment that is not halted returns the outcome unchanged. A deploy to a halted development environment also ends its halt. A deploy, promote, rollback or restart of halted production is refused target_environment_halted until you call this.

Access and action metadata #

{
  "name": "halt_environment",
  "resource": "environment",
  "tier": "reversible",
  "surface": "tzcloud",
  "addresses": [
    "tzcloud"
  ],
  "clients": [
    "bearer",
    "browser_session"
  ],
  "product": "cloud",
  "summary": "Halt your deployed environment without deleting it: requests to its hostname are refused 503 `environment_halted`, its schedule rows leave the tick's claim, and its version, data, credentials, and declarations remain. Production's compute stops. A halted development environment serves nothing, and its compute stops when idle at the latest, for either size. A container app stops in the call, and a pod's scaler is paused at zero within about 11 seconds after it. A halt on a halted environment returns `unchanged`. A halt of production is an account action: admitted under the account's session or a minted token scoped to the whole account, and refused 403 `account_credential_required` under a minted token bounded to one application, so that a leaked application-bounded token cannot stop production; a development halt and `halt_environment` with `resume: true` keep the bounded token's admission. A halt is refused `deploy_in_flight` while a deploy, promote, or restart of the environment runs, save one case. A halt of production while a production deploy is still building its image is admitted and ends that deploy; past its build, the halt is refused until the deploy ends. With `resume: true`, the hostname responds again and every schedule row restarts from the resume instant. Production's compute starts; development of either size starts on its next request. A resume on a running environment returns `unchanged`; a deploy to a halted development environment also ends its halt.",
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": true,
    "openWorldHint": true
  }
}

MCP catalog entry #

{
  "name": "halt_environment",
  "title": "Halt environment",
  "tier": "reversible",
  "scenario": "CHI-L0-09",
  "summary": "Halt your deployed environment without deleting its version, data, credentials or declarations, or resume with `resume: true`. While halted its hostname returns 503 `environment_halted` and schedules stop. Resume restarts schedules from that instant, without replaying missed runs. A deploy ends a development halt. Halted production refuses deploys, promotes, rollbacks and restarts until resumed. Halting production during its deploy's image build ends that deploy. After the build, `deploy_in_flight` refuses the halt. The account owner must have requested or agreed to this production halt. Development needs no ask. A resume needed for that agreed promote or roll back is part of the same request.",
  "owners": [
    "PLD-L0-41",
    "PLD-L0-47",
    "PLD-L0-40"
  ]
}

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 to halt or resume. Halting production needs your account's session or an account-wide token, else 403 account_credential_required. In-flight deploys, promotes or restarts refuse a halt deploy_in_flight, except a production halt during its image build, which ends that deploy.

Type: string
Pattern: ^(development|production)$
/properties/resume true ends the halt on either environment and restarts its schedules from the resume instant, without replaying runs missed during the halt.

Type: boolean

response #

JSON pointer Description and constraints
"" (root) The environment's halted state after your call; unchanged where a halt found the environment halted or a resume found it running.

Type: object
Required fields: ["contract_version","application","environment","halted","outcome","detail"]
/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/application Type: string
/properties/environment Type: string
/properties/halted False where the environment is running, never true; otherwise the halt's instant and author.

Type: ["object","boolean"]
Required fields: ["at","by"]
/properties/halted/properties/at The instant the halt began, in UTC (ISO 8601).

Type: string
/properties/halted/properties/by Who halted the environment: developer through halt_environment, or platform through the activity cap of the daily pass.

Type: string
Allowed values: ["developer","platform"]
/properties/outcome Type: string
Allowed values: ["halted","resumed","unchanged"]
/properties/detail Describes the outcome. When the call sets a halt, it explains the hostname's 503 environment_halted response, what happens to compute, and any production deploy it ended. When the call ends a halt, it describes the schedule restart and reports when a missing pod scaler prevented compute from starting. If the halt state stays as it was, it says so.

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 to halt or resume. Halting `production` needs your account's session or an account-wide token, else 403 `account_credential_required`. In-flight deploys, promotes or restarts refuse a halt `deploy_in_flight`, except a production halt during its image build, which ends that deploy."
      },
      "resume": {
        "type": "boolean",
        "description": "`true` ends the halt on either environment and restarts its schedules from the resume instant, without replaying runs missed during the halt."
      }
    }
  },
  "response": {
    "type": "object",
    "required": [
      "contract_version",
      "application",
      "environment",
      "halted",
      "outcome",
      "detail"
    ],
    "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."
      },
      "application": {
        "type": "string"
      },
      "environment": {
        "type": "string"
      },
      "halted": {
        "type": [
          "object",
          "boolean"
        ],
        "required": [
          "at",
          "by"
        ],
        "properties": {
          "at": {
            "type": "string",
            "description": "The instant the halt began, in UTC (ISO 8601)."
          },
          "by": {
            "type": "string",
            "enum": [
              "developer",
              "platform"
            ],
            "description": "Who halted the environment: `developer` through `halt_environment`, or `platform` through the activity cap of the daily pass (PLD-L0-41)."
          }
        },
        "description": "False where the environment is running, never true; otherwise the halt's instant and author (PLD-L0-41)."
      },
      "outcome": {
        "type": "string",
        "enum": [
          "halted",
          "resumed",
          "unchanged"
        ]
      },
      "detail": {
        "type": "string",
        "description": "Describes the outcome. When the call sets a halt, it explains the hostname's `503 environment_halted` response, what happens to compute, and any production deploy it ended. When the call ends a halt, it describes the schedule restart and reports when a missing pod scaler prevented compute from starting (PLD-L0-41). If the halt state stays as it was, it says so."
      }
    },
    "description": "The environment's halted state after your call; `unchanged` where a halt found the environment halted or a resume found it running (PLD-L0-41)."
  }
}

Shared contracts #