> For the complete documentation index, see [llms.txt](https://docs.vngcloud.vn/vng-cloud-document/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vngcloud.vn/vng-cloud-document/ai-stack/agent-base/agent-runtime/manage-runtime.md).

# Manage Runtime

> Guide to stopping, starting, updating, managing Endpoints, rolling back versions, and deleting an Agent Runtime.

***

## Prerequisites

* At least 1 Runtime already created
* Role Root or Admin

***

## Stop a Runtime

Stop a Runtime to save compute costs. Configuration, Endpoint, and logs are preserved.

**Step 1:** Open **Agent Runtime** → locate the Runtime to stop

**Step 2:** Click **Stop** → confirm

{% hint style="warning" %}
While the Runtime is in `STOPPED` state, all requests to its Endpoint will return an error until it is started again.
{% endhint %}

***

## Start a Runtime

**Step 1:** Open **Agent Runtime** → locate the `STOPPED` Runtime

**Step 2:** Click **Start** → Runtime transitions through `STARTING` → `ACTIVE`

***

## Update Runtime / Deploy a New Version

Each update creates a new immutable **Version**. The DEFAULT Endpoint automatically points to the latest version — the old version continues serving traffic until the deployment completes.

**Runtime topology with multiple versions:**

```
Runtime: my-order-agent
│
├── Versions
│   ├── Version 1  (image: my-agent:v1.0.0)
│   └── Version 2  (image: my-agent:v2.0.0)  ← latest
│
├── Endpoints
│   ├── DEFAULT  → https://<default-url>   (auto-tracks latest version)
│   └── canary   → https://<canary-url>    (pinned to Version 1)
│
└── Autoscaling: min=1, max=3, CPU threshold=50%
```

### Via Portal

**Step 1:** Open Runtime Detail → click **Edit**

**Step 2:** Change Image URL, Flavor, autoscaling, or environment variables → **Save**

### Via API

> Note: All fields (except `imageAuth`) are required in the PATCH body.

```bash
curl -s -X PATCH "https://agentbase.api.vngcloud.vn/runtime/agent-runtimes/$RUNTIME_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Production order agent v2",
    "imageUrl": "vcr.vngcloud.vn/<repo-backendName>/my-agent:v2.0.0",
    "imageAuth": {
      "enabled": true,
      "username": "<robot-backendName>",
      "password": "<robot-secret>"
    },
    "command": [],
    "args": [],
    "environmentVariables": {"LOG_LEVEL": "info"},
    "flavorId": "1x1-general",
    "autoscaling": {
      "minReplicas": 1,
      "maxReplicas": 3,
      "cpuUtilization": 50,
      "memoryUtilization": 50
    }
  }' | jq .
```

***

## Manage Endpoints

Each Runtime has one **DEFAULT** Endpoint created automatically. You can create additional Endpoints pinned to specific versions for canary or staging traffic.

### Via Portal

**View Endpoints:** Open Runtime Detail → **Endpoints** tab

![Runtime detail — Endpoints tab](/files/pi6PJw1vk0AXe7XW2RBi)

**Create a new Endpoint:**

1. **Endpoints** tab → click **Create Endpoint**
2. Enter **Name** and select **Version** → **Create**

**Change an Endpoint's version:**

1. **Endpoints** tab → click an endpoint → **Edit**
2. Select a new **Version** → **Save**

### Via API

**List Endpoints:**

```bash
curl -s "https://agentbase.api.vngcloud.vn/runtime/agent-runtimes/$RUNTIME_ID/endpoints?page=1&size=20" \
  -H "Authorization: Bearer $TOKEN" | jq .
```

Fields returned: `id`, `agentRuntimeId`, `name`, `version`, `url`, `status`, `createdAt`, `updatedAt`

**Create an Endpoint:**

```bash
curl -s -X POST "https://agentbase.api.vngcloud.vn/runtime/agent-runtimes/$RUNTIME_ID/endpoints" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "canary", "version": 2}' | jq .
```

**Update an Endpoint's version:**

```bash
curl -s -X PATCH "https://agentbase.api.vngcloud.vn/runtime/agent-runtimes/$RUNTIME_ID/endpoints/$ENDPOINT_ID?version=3" \
  -H "Authorization: Bearer $TOKEN" | jq .
```

**Delete an Endpoint:**

```bash
curl -s -X DELETE "https://agentbase.api.vngcloud.vn/runtime/agent-runtimes/$RUNTIME_ID/endpoints/$ENDPOINT_ID" \
  -H "Authorization: Bearer $TOKEN"
```

***

## View Versions and Rollback

Each update creates a new immutable Version. To roll back, point the DEFAULT Endpoint to an older version number.

### Via Portal

Open Runtime Detail → **Versions** tab

![Runtime detail — Versions tab](/files/J4xdmh3dm3jBi45MXPyS)

### Via API

**List versions:**

```bash
curl -s "https://agentbase.api.vngcloud.vn/runtime/agent-runtimes/$RUNTIME_ID/versions?page=1&size=20" \
  -H "Authorization: Bearer $TOKEN" | jq .
```

Fields returned: `agentRuntimeId`, `version` (integer), `imageUrl`, `flavorId`, `autoscaling`, `createdAt`

**Rollback to an older version:**

```bash
ENDPOINT_ID=$(curl -s "https://agentbase.api.vngcloud.vn/runtime/agent-runtimes/$RUNTIME_ID/endpoints?page=1&size=10" \
  -H "Authorization: Bearer $TOKEN" | jq -r '.listData[] | select(.name=="DEFAULT") | .id')

curl -s -X PATCH "https://agentbase.api.vngcloud.vn/runtime/agent-runtimes/$RUNTIME_ID/endpoints/$ENDPOINT_ID?version=1" \
  -H "Authorization: Bearer $TOKEN" | jq .
```

***

## Delete a Runtime

{% hint style="warning" %}
Deleting a Runtime is **irreversible**. All versions, Endpoints, and logs are permanently deleted.
{% endhint %}

### Via Portal

**Step 1:** Open **Agent Runtime** → locate the Runtime to delete

**Step 2:** Click **Delete** → review the warning → confirm

### Via API

```bash
curl -s -X DELETE "https://agentbase.api.vngcloud.vn/runtime/agent-runtimes/$RUNTIME_ID" \
  -H "Authorization: Bearer $TOKEN"
```

***

## Reset Service Account

If IAM service account credentials are changed or revoked, use this to recover the Runtime:

```bash
curl -s -X PATCH "https://agentbase.api.vngcloud.vn/runtime/agent-runtimes/$RUNTIME_ID/reset-service-account" \
  -H "Authorization: Bearer $TOKEN" | jq .
```

{% hint style="warning" %}
This regenerates `GREENNODE_CLIENT_ID` and `GREENNODE_CLIENT_SECRET`. The Runtime restarts with new credentials.
{% endhint %}

***

## Next Steps

| I want to...          | Go to                                                                                |
| --------------------- | ------------------------------------------------------------------------------------ |
| View logs and metrics | [Insight](/vng-cloud-document/ai-stack/agent-base/agent-runtime/logs-and-metrics.md) |
| Configure MCP Gateway | [MCP Governance](/vng-cloud-document/ai-stack/agent-base/mcp-governance.md)          |


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.vngcloud.vn/vng-cloud-document/ai-stack/agent-base/agent-runtime/manage-runtime.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.