> For the complete documentation index, see [llms.txt](https://docs.kinesis.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kinesis.network/mcp/tools/lifecycle.md).

# App lifecycle

Inspect desired and actual app state, then start, stop, restart or delete.

Inspect desired and actual app state, then start, stop, restart or delete.

These are action names. In default compact mode, call the indicated group tool with `{"action":"<action-name>","params":{...}}`; the arguments below go inside `params`. In `?mode=all`, call the action name directly with those arguments. `browse_github` and `read_docs` are direct tools in both modes. Expand each schema for nested fields, enum values and validation constraints. Successful results are JSON in both text content and `structuredContent`; failures use `isError` and `structuredContent.error`.

The [OpenAI profile](/mcp/openai-profile.md) calls individual actions, omits `get_byod_token`, and restricts credential inputs and environment outputs. The input schemas below describe the standard catalog; profile-specific schemas are included where they differ.

## `get_app_status`

Read the live status of an app from the runtime. Aggregate state, each server's container state, where each port answers, recent errors. Poll this after start, stop or delete.

**Group:** `apps` · **Behavior:** Read

**Compact tool:** `apps` · **Action:** `get_app_status`

**MCP annotations:** `readOnlyHint: true` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false`

### Permissions and REST equivalents

| Operation     | REST                                            | Required scopes |
| ------------- | ----------------------------------------------- | --------------- |
| `apps.status` | `GET /projects/{projectId}/apps/{appId}/status` | `apps:read`     |

### Arguments

| Argument    | Type     | Required | Description |
| ----------- | -------- | -------- | ----------- |
| `projectId` | `string` | Yes      | Project id  |
| `appId`     | `string` | Yes      | App id      |

<details>

<summary>Complete input schema</summary>

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "projectId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{24}$",
      "description": "Project id"
    },
    "appId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{24}$",
      "description": "App id"
    }
  },
  "required": [
    "projectId",
    "appId"
  ],
  "additionalProperties": false
}
```

</details>

### Result

* `state` (`"unknown" / "running" / "stopped" / "starting" / "stopping" / "scaling" / "updating" / "downloading" / "provisioning" / "start_blocked" / "error" / "building" / "build_failed"`): Aggregate state; build states win while there is no runnable image
* `targetState` (`"running" / "stopped" / "unknown"`): What the runtime was last asked for; unknown until it has been asked, as for a repository app before its first build succeeds
* `nodes` (`array<object>`): Servers the app is placed on and the container state on each
* `endpoints` (`array<object>`): Where each configured port answers; a load-balanced port gets its address a minute or two after the first start
* `errors` (`array<object>`): Recent runtime errors, newest first
* `workOrders` (`array<object>`): The runtime's latest instructions to servers, newest first; an order that never completes is the stall
* `grid` (`object or null`): Grid placement details; null for a serverless app
* `pollAfterSec` (`integer or null`): Seconds to wait before reading the status again while it is changing; null in a settled state
* `id` (`string`): App id

<details>

<summary>Response schema: apps.status</summary>

```json
{
  "type": "object",
  "properties": {
    "state": {
      "type": "string",
      "enum": [
        "unknown",
        "running",
        "stopped",
        "starting",
        "stopping",
        "scaling",
        "updating",
        "downloading",
        "provisioning",
        "start_blocked",
        "error",
        "building",
        "build_failed"
      ],
      "description": "Aggregate state; build states win while there is no runnable image"
    },
    "targetState": {
      "type": "string",
      "enum": [
        "running",
        "stopped",
        "unknown"
      ],
      "description": "What the runtime was last asked for; unknown until it has been asked, as for a repository app before its first build succeeds"
    },
    "nodes": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "address": {
            "type": "string"
          },
          "state": {
            "type": "string"
          },
          "reportedAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 timestamp (UTC)"
              },
              {
                "type": "null"
              }
            ],
            "description": "When the server last reported this state; not a start time"
          }
        },
        "required": [
          "address",
          "state",
          "reportedAt"
        ],
        "additionalProperties": false
      },
      "description": "Servers the app is placed on and the container state on each"
    },
    "endpoints": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "port": {
            "type": "integer",
            "description": "Container port, as in config.ports"
          },
          "protocol": {
            "type": "string",
            "description": "Protocol of that port, as in config.ports"
          },
          "address": {
            "description": "An http(s) URL for the HTTP protocols, host:port for the others; null until the endpoint is wired",
            "type": [
              "string",
              "null"
            ]
          },
          "server": {
            "description": "Server address of a direct tcp or udp endpoint; null when load-balanced",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "port",
          "protocol",
          "address",
          "server"
        ],
        "additionalProperties": false
      },
      "description": "Where each configured port answers; a load-balanced port gets its address a minute or two after the first start"
    },
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "at": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 timestamp (UTC)"
              },
              {
                "type": "null"
              }
            ]
          },
          "details": {
            "anyOf": [
              {
                "type": "object",
                "propertyNames": {
                  "type": "string"
                },
                "additionalProperties": {}
              },
              {
                "type": "null"
              }
            ],
            "description": "Extra data the runtime attached, such as the grid or server involved"
          }
        },
        "required": [
          "type",
          "message",
          "at",
          "details"
        ],
        "additionalProperties": false
      },
      "description": "Recent runtime errors, newest first"
    },
    "workOrders": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "What the runtime asked the server to do"
          },
          "server": {
            "type": "string",
            "description": "Server address"
          },
          "status": {
            "type": "string"
          },
          "createdAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 timestamp (UTC)"
              },
              {
                "type": "null"
              }
            ]
          },
          "startedAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 timestamp (UTC)"
              },
              {
                "type": "null"
              }
            ]
          },
          "completedAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 timestamp (UTC)"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "type",
          "server",
          "status",
          "createdAt",
          "startedAt",
          "completedAt"
        ],
        "additionalProperties": false
      },
      "description": "The runtime's latest instructions to servers, newest first; an order that never completes is the stall"
    },
    "grid": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "fill": {
              "anyOf": [
                {
                  "type": "object",
                  "properties": {
                    "target": {
                      "type": "integer",
                      "description": "Members the grid is composed to have"
                    },
                    "online": {
                      "type": "integer",
                      "description": "Members the app runs on"
                    },
                    "pending": {
                      "type": "integer"
                    },
                    "converging": {
                      "type": "boolean",
                      "description": "The grid is still acquiring members or placing the app"
                    }
                  },
                  "required": [
                    "target",
                    "online",
                    "pending",
                    "converging"
                  ],
                  "additionalProperties": false
                },
                {
                  "type": "null"
                }
              ],
              "description": "How far the grid has filled for this app"
            },
            "idleReclaim": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "gridId": {
                    "type": "string"
                  },
                  "warnedAt": {
                    "anyOf": [
                      {
                        "type": "string",
                        "format": "date-time",
                        "description": "ISO 8601 timestamp (UTC)"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "evictAt": {
                    "anyOf": [
                      {
                        "type": "string",
                        "format": "date-time",
                        "description": "ISO 8601 timestamp (UTC)"
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "When the app becomes evictable; null when the grid only warns"
                  },
                  "evictedAt": {
                    "anyOf": [
                      {
                        "type": "string",
                        "format": "date-time",
                        "description": "ISO 8601 timestamp (UTC)"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "cooldownEndsAt": {
                    "anyOf": [
                      {
                        "type": "string",
                        "format": "date-time",
                        "description": "ISO 8601 timestamp (UTC)"
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "When the grid takes the app again after an eviction"
                  },
                  "evidence": {
                    "type": "string",
                    "description": "Why the grid considers the app idle"
                  }
                },
                "required": [
                  "gridId",
                  "warnedAt",
                  "evictAt",
                  "evictedAt",
                  "cooldownEndsAt",
                  "evidence"
                ],
                "additionalProperties": false
              },
              "description": "Grids whose idle policy has warned or evicted the app"
            },
            "queue": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "gridId": {
                    "type": "string"
                  },
                  "position": {
                    "type": "integer",
                    "description": "1-based place in the grid's fair-share queue"
                  },
                  "queueLength": {
                    "type": "integer"
                  },
                  "enqueuedAt": {
                    "anyOf": [
                      {
                        "type": "string",
                        "format": "date-time",
                        "description": "ISO 8601 timestamp (UTC)"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "held": {
                    "type": "boolean",
                    "description": "The scheduler keeps the app off the grid until its turn comes"
                  }
                },
                "required": [
                  "gridId",
                  "position",
                  "queueLength",
                  "enqueuedAt",
                  "held"
                ],
                "additionalProperties": false
              },
              "description": "Full grids the app is queued on"
            }
          },
          "required": [
            "fill",
            "idleReclaim",
            "queue"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ],
      "description": "Grid placement details; null for a serverless app"
    },
    "pollAfterSec": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "description": "Seconds to wait before reading the status again while it is changing; null in a settled state"
    },
    "id": {
      "type": "string",
      "description": "App id"
    }
  },
  "required": [
    "state",
    "targetState",
    "nodes",
    "endpoints",
    "errors",
    "workOrders",
    "grid",
    "pollAfterSec",
    "id"
  ],
  "additionalProperties": false
}
```

</details>

## `start_app`

Ask the runtime to start an app. Returns once the request is accepted; poll the status to follow it.

**Group:** `apps` · **Behavior:** Write

**Compact tool:** `apps_write` · **Action:** `start_app`

**MCP annotations:** `readOnlyHint: false` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: true`

### Permissions and REST equivalents

| Operation    | REST                                            | Required scopes               |
| ------------ | ----------------------------------------------- | ----------------------------- |
| `apps.start` | `POST /projects/{projectId}/apps/{appId}/start` | `apps:write`, `compute:spend` |

### Arguments

| Argument    | Type     | Required | Description |
| ----------- | -------- | -------- | ----------- |
| `projectId` | `string` | Yes      | Project id  |
| `appId`     | `string` | Yes      | App id      |

<details>

<summary>Complete input schema</summary>

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "projectId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{24}$",
      "description": "Project id"
    },
    "appId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{24}$",
      "description": "App id"
    }
  },
  "required": [
    "projectId",
    "appId"
  ],
  "additionalProperties": false
}
```

</details>

### Result

* `id` (`string`): App id
* `targetState` (`"running" / "stopped"`): State the runtime is now converging on

<details>

<summary>Response schema: apps.start</summary>

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "App id"
    },
    "targetState": {
      "type": "string",
      "enum": [
        "running",
        "stopped"
      ],
      "description": "State the runtime is now converging on"
    }
  },
  "required": [
    "id",
    "targetState"
  ],
  "additionalProperties": false
}
```

</details>

Operation-specific errors: `402 balance_over_limit`, `429 grid_quota_exceeded`, `403 serverless_disabled`.

## `stop_app`

Ask the runtime to stop an app. Returns once the request is accepted; poll the status to follow it.

**Group:** `apps` · **Behavior:** Write

**Compact tool:** `apps_write` · **Action:** `stop_app`

**MCP annotations:** `readOnlyHint: false` · `destructiveHint: true` · `idempotentHint: true` · `openWorldHint: false`

### Permissions and REST equivalents

| Operation   | REST                                           | Required scopes |
| ----------- | ---------------------------------------------- | --------------- |
| `apps.stop` | `POST /projects/{projectId}/apps/{appId}/stop` | `apps:write`    |

### Arguments

| Argument    | Type     | Required | Description |
| ----------- | -------- | -------- | ----------- |
| `projectId` | `string` | Yes      | Project id  |
| `appId`     | `string` | Yes      | App id      |

<details>

<summary>Complete input schema</summary>

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "projectId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{24}$",
      "description": "Project id"
    },
    "appId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{24}$",
      "description": "App id"
    }
  },
  "required": [
    "projectId",
    "appId"
  ],
  "additionalProperties": false
}
```

</details>

### Result

* `id` (`string`): App id
* `targetState` (`"running" / "stopped"`): State the runtime is now converging on

<details>

<summary>Response schema: apps.stop</summary>

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "App id"
    },
    "targetState": {
      "type": "string",
      "enum": [
        "running",
        "stopped"
      ],
      "description": "State the runtime is now converging on"
    }
  },
  "required": [
    "id",
    "targetState"
  ],
  "additionalProperties": false
}
```

</details>

## `restart_app`

Stop an app, wait for it to report stopped, then start it again. It waits up to waitSec (default 30); if the app is still stopping when the wait runs out the start is issued anyway; check get\_app\_status afterwards.

**Group:** `apps` · **Behavior:** Write

**Compact tool:** `apps_write` · **Action:** `restart_app`

**MCP annotations:** `readOnlyHint: false` · `destructiveHint: true` · `idempotentHint: false` · `openWorldHint: true`

### Permissions and REST equivalents

| Operation      | REST                                              | Required scopes               |
| -------------- | ------------------------------------------------- | ----------------------------- |
| `apps.restart` | `POST /projects/{projectId}/apps/{appId}/restart` | `apps:write`, `compute:spend` |

### Arguments

| Argument    | Type      | Required | Description                                                         |
| ----------- | --------- | -------- | ------------------------------------------------------------------- |
| `waitSec`   | `integer` | No       | Seconds to wait for the stop before starting, 0 to 180 (default 30) |
| `projectId` | `string`  | Yes      | Project id                                                          |
| `appId`     | `string`  | Yes      | App id                                                              |

<details>

<summary>Complete input schema</summary>

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "waitSec": {
      "type": "integer",
      "minimum": 0,
      "maximum": 180,
      "description": "Seconds to wait for the stop before starting, 0 to 180 (default 30)"
    },
    "projectId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{24}$",
      "description": "Project id"
    },
    "appId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{24}$",
      "description": "App id"
    }
  },
  "required": [
    "projectId",
    "appId"
  ],
  "additionalProperties": false
}
```

</details>

### Result

* `id` (`string`): App id
* `targetState` (`"running"`): State the runtime is now converging on
* `stoppedBeforeStart` (`boolean`): The app reported stopped before the start was issued; false when the wait ran out
* `waitedSec` (`integer`): Seconds spent waiting for the stop

<details>

<summary>Response schema: apps.restart</summary>

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "App id"
    },
    "targetState": {
      "type": "string",
      "const": "running",
      "description": "State the runtime is now converging on"
    },
    "stoppedBeforeStart": {
      "type": "boolean",
      "description": "The app reported stopped before the start was issued; false when the wait ran out"
    },
    "waitedSec": {
      "type": "integer",
      "description": "Seconds spent waiting for the stop"
    }
  },
  "required": [
    "id",
    "targetState",
    "stoppedBeforeStart",
    "waitedSec"
  ],
  "additionalProperties": false
}
```

</details>

Operation-specific errors: `402 balance_over_limit`, `429 grid_quota_exceeded`, `403 serverless_disabled`.

## `delete_app`

Delete a stopped app (admins, or its creator). Fails with app\_running while any node is still live. Irreversible.

**Group:** `apps` · **Behavior:** Write

**Compact tool:** `apps_write` · **Action:** `delete_app`

**MCP annotations:** `readOnlyHint: false` · `destructiveHint: true` · `idempotentHint: false` · `openWorldHint: false`

Requires `confirm: true` for this irreversible action.

### Permissions and REST equivalents

| Operation     | REST                                        | Required scopes |
| ------------- | ------------------------------------------- | --------------- |
| `apps.delete` | `DELETE /projects/{projectId}/apps/{appId}` | `apps:admin`    |

### Arguments

| Argument    | Type     | Required | Description                                |
| ----------- | -------- | -------- | ------------------------------------------ |
| `projectId` | `string` | Yes      | Project id                                 |
| `appId`     | `string` | Yes      | App id                                     |
| `confirm`   | `true`   | Yes      | Must be true: this action cannot be undone |

<details>

<summary>Complete input schema</summary>

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "projectId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{24}$",
      "description": "Project id"
    },
    "appId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{24}$",
      "description": "App id"
    },
    "confirm": {
      "type": "boolean",
      "const": true,
      "description": "Must be true: this action cannot be undone"
    }
  },
  "required": [
    "projectId",
    "appId",
    "confirm"
  ],
  "additionalProperties": false
}
```

</details>

### Result

* `id` (`string`): Id of the deleted app
* `deleted` (`true`): See the complete response schema below.

<details>

<summary>Response schema: apps.delete</summary>

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Id of the deleted app"
    },
    "deleted": {
      "type": "boolean",
      "const": true
    }
  },
  "required": [
    "id",
    "deleted"
  ],
  "additionalProperties": false
}
```

</details>

Operation-specific errors: `409 app_running`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.kinesis.network/mcp/tools/lifecycle.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.