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

This call turns on an application's development environment. Turning development on removes no production test end user. Your signed-in session or a token with the test_end_users grant can still create them on production. New applications have only production and deploy there. With development on, deploy targets it. promote moves a version to production. The optional environment accepts only development. The call finishes before returning. It creates development's sign-in realm if the manifest declares accounts, records realm and push settings, and declares schedules. It provisions no database. submit_manifest provisions development's database before or after this call. Nothing runs there before its first deploy.

If development is already on, the answer is created: false. The call still repairs realm, settings or schedule steps a failed call left incomplete. delete_environment turns development off.

Access and action metadata #

{
  "name": "create_environment",
  "resource": "environment",
  "tier": "reversible",
  "surface": "tzcloud",
  "addresses": [
    "tzcloud"
  ],
  "product": "cloud",
  "summary": "This call turns on an application's development environment. Turning development on removes no production test end user. Your signed-in session or a token with the `test_end_users` grant can still create them on production. New applications have only production and deploy there. With development on, `deploy` targets it. `promote` moves a version to production. The optional `environment` accepts only `development`. The call finishes before returning. It creates development's sign-in realm if the manifest declares accounts, records realm and push settings, and declares schedules. It provisions no database. `submit_manifest` provisions development's database before or after this call. Nothing runs there before its first `deploy`.\n\nIf development is already on, the answer is `created: false`. The call still repairs realm, settings or schedule steps a failed call left incomplete. `delete_environment` turns development off.",
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": false,
    "idempotentHint": true,
    "openWorldHint": false
  }
}

MCP catalog entry #

{
  "name": "create_environment",
  "title": "Create development environment",
  "tier": "reversible",
  "scenario": "CHI-L0-07",
  "summary": "This call turns on an application's development environment. Turning development on removes no production test end user. Your signed-in session or a token with the `test_end_users` grant can still create them on production. New applications have only production and deploy there. With development on, `deploy` targets it. `promote` moves a version to production. The optional `environment` accepts only `development`. The call finishes before returning. It creates development's sign-in realm if the manifest declares accounts, records realm and push settings, and declares schedules. It provisions no database. `submit_manifest` provisions development's database before or after this call. Nothing runs there before its first `deploy`.\n\nIf development is already on, the answer is `created: false`. The call still repairs realm, settings or schedule steps a failed call left incomplete. `delete_environment` turns development off.",
  "owners": [
    "PLD-L0-96",
    "PLD-L0-40",
    "ACS-L0-21"
  ]
}

request #

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

Type: string
/properties/environment Optional: leave it out for development, the one environment an application can add; production is refused invalid_request, because production always exists.

Type: string
Pattern: ^(development|production)$

response #

JSON pointer Description and constraints
"" (root) The development environment turned on, or found on. Nothing hosted is created and no database is provisioned: call submit_manifest before or after this call to provision development's database, and development holds compute from its first deploy.

Type: object
Required fields: ["contract_version","application","environment","created","environments","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/application Type: string
/properties/environment Required value: development
/properties/created True where this call turned development on, recording on development the recorded manifest's realm member and push entry where it carries them. False where the application already had two environments: the call wrote no count, repaired its development realm and schedules, and recorded only what development lacked.

Type: boolean
/properties/environments The environments the application has after the call: development and production.

Type: array
/properties/environments/items Type: string
Allowed values: ["development","production"]
/properties/hostname The development hostname, <label>-dev.ai.host, which serves the application's first deploy to development.

Type: string
/properties/realm The development sign-in realm, where the recorded manifest declares the accounts service: local runs and the development hostname then sign testers in on it, with accounts of its own.

Type: object
Required fields: ["realm","outcome"]
/properties/realm/properties/realm Type: string
/properties/realm/properties/outcome Type: string
Allowed values: ["created","confirmed"]
/properties/detail What changed and the next call, one fact per line: submit_manifest where no manifest is recorded, where development lacks the database the manifest declares, or where delete_environment removed development's records and no submission ran since; deploy_command otherwise.

Type: string
/properties/page $ref: #/shapes/page

Complete payload contract #

{
  "request": {
    "type": "object",
    "required": [
      "application"
    ],
    "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": "Optional: leave it out for `development`, the one environment an application can add; `production` is refused `invalid_request`, because production always exists."
      }
    }
  },
  "response": {
    "type": "object",
    "required": [
      "contract_version",
      "application",
      "environment",
      "created",
      "environments",
      "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."
      },
      "application": {
        "type": "string"
      },
      "environment": {
        "const": "development"
      },
      "created": {
        "type": "boolean",
        "description": "True where this call turned development on, recording on development the recorded manifest's `realm` member and push entry where it carries them. False where the application already had two environments: the call wrote no count, repaired its development realm and schedules, and recorded only what development lacked."
      },
      "environments": {
        "type": "array",
        "items": {
          "type": "string",
          "enum": [
            "development",
            "production"
          ]
        },
        "description": "The environments the application has after the call: development and production."
      },
      "hostname": {
        "type": "string",
        "description": "The development hostname, `<label>-dev.ai.host`, which serves the application's first deploy to development."
      },
      "realm": {
        "type": "object",
        "required": [
          "realm",
          "outcome"
        ],
        "properties": {
          "realm": {
            "type": "string"
          },
          "outcome": {
            "type": "string",
            "enum": [
              "created",
              "confirmed"
            ]
          }
        },
        "description": "The development sign-in realm, where the recorded manifest declares the accounts service: local runs and the development hostname then sign testers in on it, with accounts of its own."
      },
      "detail": {
        "type": "string",
        "description": "What changed and the next call, one fact per line: `submit_manifest` where no manifest is recorded, where development lacks the database the manifest declares, or where `delete_environment` removed development's records and no submission ran since; `deploy_command` otherwise."
      },
      "page": {
        "$ref": "#/shapes/page"
      }
    },
    "description": "The development environment turned on, or found on (PLD-L0-96). Nothing hosted is created and no database is provisioned: call `submit_manifest` before or after this call to provision development's database, and development holds compute from its first deploy."
  }
}

Shared contracts #