> For the complete documentation index, see [llms.txt](https://docs.greennode.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.greennode.ai/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](/ai-stack/agent-base/container-registry.md))
* An Identity created for the agent — see [Access Control](/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.greennode.ai/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](/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](/ai-stack/agent-base/agent-runtime/manage-runtime.md) |
| Attach a Policy Group to a Gateway | [Policy Groups](/ai-stack/agent-base/mcp-governance/policy-groups.md)  |