> 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/create-runtime.md).

# Create Runtime

> Step-by-step guide to creating an Agent Runtime from a container image on GreenNode AgentBase.

***

## Prerequisites

* A GreenNode account with role Root or Admin
* A container image for your agent (public registry or [private Container Registry](/vng-cloud-document/ai-stack/agent-base/container-registry.md))
* An Identity created for the agent — see [Access Control](/vng-cloud-document/ai-stack/agent-base/access-control.md)

***

## Quick Deploy with AgentBase Skills

If you use **Claude Code**, **Cursor**, or Codex, GreenNode provides a skills kit at [github.com/vngcloud/greennode-agentbase-skills](https://github.com/vngcloud/greennode-agentbase-skills) — a set of slash commands that automate the full workflow from scaffolding to deployment in one guided flow.

**Install:**

```bash
# Clone skills into your project
git clone https://github.com/vngcloud/greennode-agentbase-skills .claude/skills/agentbase
```

**Use in Claude Code / Cursor:**

| Skill                 | What it does                                                               |
| --------------------- | -------------------------------------------------------------------------- |
| `/agentbase-wizard`   | Full 9-step workflow: scaffold → configure → code → test → deploy → verify |
| `/agentbase-deploy`   | Build container, push image, and deploy to Runtime                         |
| `/agentbase-monitor`  | View logs, metrics, and Runtime status                                     |
| `/agentbase-identity` | Configure IAM Identity for your agent                                      |

Recommended for developers who want to integrate deployment into an AI-assisted coding workflow without manual Portal steps.

***

## Create via Portal

**Step 1:** Open [Agent Runtime](https://aiplatform.console.vngcloud.vn/agent-runtime?tab=runtime) → click **Deploy a new Agent**

A popup appears to choose the agent type:

![Deploy a new Agent — choose agent type](/files/IkVfJJzMhMFRrcEGKdB7)

| Type             | Description                                                                                         |
| ---------------- | --------------------------------------------------------------------------------------------------- |
| **Custom Agent** | Agent you code and deploy yourself — full control over runtime, vCR, IAM, and scaling               |
| **OpenClaw**     | Platform-managed agent, pre-configured by GreenNode — quick deploy, no runtime configuration needed |

Click **DEPLOY** in the **Custom Agent** card to continue.

**Step 2:** Fill in the required information

| Field                     | Example                              | Notes                                     |
| ------------------------- | ------------------------------------ | ----------------------------------------- |
| **Name**                  | `my-order-agent`                     | Unique, lowercase, hyphens allowed        |
| **Description**           | `Production order agent`             | Optional                                  |
| **Image URL**             | `vcr.vngcloud.vn/<repo>/my-agent:v1` | Full image path including tag             |
| **Flavor**                | `1x1-general`                        | 1 vCPU, 1 GB RAM                          |
| **Min Replicas**          | `1`                                  | Range: 1–10                               |
| **Max Replicas**          | `1`                                  | Set >1 to enable autoscaling              |
| **CPU Threshold**         | `50`                                 | Scale out when CPU exceeds this % (25–75) |
| **Memory Threshold**      | `50`                                 | Scale out when RAM exceeds this % (25–75) |
| **Registry Auth**         | Enable if private                    | Username = robot account `backendName`    |
| **Environment Variables** | `KEY=value`                          | Non-sensitive config only                 |

**Step 3:** Configure networking (optional)

* **Private VPC**: enable to deploy inside your enterprise network

**Step 4:** Configure Endpoint — AgentBase automatically creates a **DEFAULT** Endpoint

**Step 5:** Review → click **Create**

The Runtime transitions from `CREATING` → `ACTIVE` once the container starts successfully.

***

## Create via API

> Requires `$TOKEN` — an IAM bearer token. See [Getting Started](/vng-cloud-document/ai-stack/agent-base/getting-started.md#configure-authentication) to obtain one.

**Public registry image:**

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

**Private registry image (imageAuth required):**

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

**Poll until ACTIVE:**

```bash
RUNTIME_ID="<id-from-response>"
while true; do
  STATUS=$(curl -s "https://agentbase.api.vngcloud.vn/runtime/agent-runtimes/$RUNTIME_ID" \
    -H "Authorization: Bearer $TOKEN" | jq -r '.status')
  echo "Status: $STATUS"
  [ "$STATUS" = "ACTIVE" ] && break
  sleep 10
done
```

***

## Service Contract

Your agent container must satisfy the following requirements to work with the Runtime:

### Port and Health Check

| Requirement  | Value         | Notes                       |
| ------------ | ------------- | --------------------------- |
| Listen port  | `8080`        | Required — not configurable |
| Health check | `GET /health` | Must return HTTP 200        |

**Using the greennode-agentbase SDK (recommended):**

```python
from greennode_agentbase import GreenNodeAgentBaseApp, RequestContext

app = GreenNodeAgentBaseApp()

@app.entrypoint
def handler(payload: dict, context: RequestContext) -> dict:
    return {"output": "Hello!"}

if __name__ == "__main__":
    import os
    app.run(host="0.0.0.0", port=int(os.environ.get("PORT", "8080")))
```

**Without SDK (FastAPI example):**

```python
from fastapi import FastAPI

app = FastAPI()

@app.get("/health")
def health():
    return {"status": "ok"}

@app.post("/invoke")
def invoke(body: dict):
    return {"output": f"Echo: {body.get('input', '')}"}
```

### Auto-Injected Environment Variables

The Runtime automatically injects these into every container:

| Variable                   | Description                       |
| -------------------------- | --------------------------------- |
| `GREENNODE_CLIENT_ID`      | IAM service account client ID     |
| `GREENNODE_CLIENT_SECRET`  | IAM service account client secret |
| `GREENNODE_AGENT_IDENTITY` | The agent identity name           |

### Request Headers

Incoming requests to your agent include:

| Header                             | Description                                                 |
| ---------------------------------- | ----------------------------------------------------------- |
| `X-GreenNode-AgentBase-User-Id`    | End-user ID — use as `actorId` for memory operations        |
| `X-GreenNode-AgentBase-Session-Id` | Session ID — use as `thread_id` for LangGraph checkpointing |

{% hint style="warning" %}
If your agent uses memory, validate that these headers are present and return an error if missing. Do not fall back to default values — silent defaults cause data mixing between users.
{% endhint %}

***

## Next Steps

| I want to...                       | Go to                                                                                     |
| ---------------------------------- | ----------------------------------------------------------------------------------------- |
| Stop, start, or update the Runtime | [Manage Runtime](/vng-cloud-document/ai-stack/agent-base/agent-runtime/manage-runtime.md) |
| Attach a Policy Group to a Gateway | [Policy Groups](/vng-cloud-document/ai-stack/agent-base/mcp-governance/policy-groups.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/create-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.