Skip to content

Huyenttn3 #57

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
greennode-vdb merged 2 commits into from
Oct 29, 2026
Merged

Huyenttn3 #57

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e5a9dfc
[docs] AgentBase — Built-in Tools (Code Interpreter & Browser) — VI + EN
Hana-Hasa Oct 29, 2026
c318887
[docs] AI Platform Guardrail — VI + EN
Hana-Hasa Oct 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions English/SUMMARY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -753,6 +753,9 @@
* [Import Model Registry Using Triton](ai-stack/ai-platform/model-registry/import-model-registry-using-triton.md)
* [Import Model Registry Using vLLM](ai-stack/ai-platform/model-registry/import-model-registry-using-vllm.md)
* [Import Model Registry Using a Custom Container](ai-stack/ai-platform/model-registry/import-model-registry-using-a-custom-container.md)
* [Guardrail](ai-stack/ai-platform/guardrail/README.md)
* [Using Guardrails](ai-stack/ai-platform/guardrail/using-guardrails.md)
* [Reference and FAQ](ai-stack/ai-platform/guardrail/reference-and-faq.md)
* [Model as a Service (MaaS)](ai-stack/model-as-a-service/README.md)
* [Understanding AI Models](ai-stack/model-as-a-service/understanding-ai-models.md)
* [Playground](ai-stack/model-as-a-service/playground.md)
Expand Down Expand Up @@ -802,6 +805,10 @@
* [Deploy & Manage OpenClaw](ai-stack/agent-base/agent-runtime/openclaw/deploy-and-manage-openclaw.md)
* [Get Bot Token & Pairing](ai-stack/agent-base/agent-runtime/openclaw/get-bot-token-and-pairing.md)
* [Limitations & Notes](ai-stack/agent-base/agent-runtime/openclaw/limitations-and-notes.md)
* [Built-in Tools](ai-stack/agent-base/built-in-tools/README.md)
* [Use Code Interpreter](ai-stack/agent-base/built-in-tools/use-code-interpreter.md)
* [Use Browser](ai-stack/agent-base/built-in-tools/use-browser.md)
* [Sandbox: security and limits](ai-stack/agent-base/built-in-tools/sandbox-security-and-limits.md)
* [Container Registry](ai-stack/agent-base/container-registry/README.md)
* [Team & Permissions](ai-stack/agent-base/team-permissions/README.md)
* [Manage Members](ai-stack/agent-base/team-permissions/manage-members.md)
Expand Down
82 changes: 82 additions & 0 deletions English/ai-stack/agent-base/built-in-tools/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
# Built-in Tools

Built-in Tools let your agent **run code** and **drive a real browser** inside a sandbox that is isolated per session — without provisioning any infrastructure, image, or container of your own.

Two tools are available:

| Tool | Use it to |
|---|---|
| **Code Interpreter** | Run Python and shell commands, read/write files, run background processes — each session in its own microVM |
| **Browser** | Drive a real Chrome (via CDP), watch the screen live over noVNC, and replay session recordings |

Both tools integrate over **MCP** — your agent connects to an MCP endpoint provisioned by GreenNode, and the tools appear like any other MCP tools.

{% hint style="info" %}
Built-in Tools is currently being rolled out by **whitelist**. If your account is not yet enabled, contact [support@greennode.ai](mailto:support@greennode.ai), hotline **19001549**, or the [Support Center](https://helpdesk.greennode.ai/portal/vi/home) to be added to the list.
{% endhint %}

---

## Architecture

Each of your sessions runs inside its own microVM with a dedicated kernel, claimed from a pre-warmed VM pool, so creating a session takes only a few seconds.

```
Agent / MCP client
│ MCP (HTTPS)
▼
Built-in Tools gateway
(Code Interpreter · Browser)
│
▼
AgentBase Runtime ── OpenSandbox (warm VM pool)
│
▼
Dedicated vKS node group (nested virtualization)
│ Kata Containers + Cloud Hypervisor
▼
Each session = 1 microVM with its own kernel
```

Main layers:

- **Built-in Tools** — the product layer: manages resources you own (each Code Interpreter / Browser has an id, name, status), plus quotas, authentication, and lifecycle. The sandbox runtime underneath stays hidden — its id and URL are never exposed.
- **AgentBase Runtime + OpenSandbox** — the platform layer: creates and keeps VMs warm (Pool), assigns one VM per new session, and reclaims it when the session ends.
- **Dedicated vKS node group** — sandbox workloads are separated onto a dedicated node group on vKS with **nested virtualization** enabled and the `nested-virt` taint so regular pods cannot take those nodes. Each sandbox pod runs through RuntimeClass `kata-clh` (Kata Containers + Cloud Hypervisor).

### Why one microVM per session?

Agents need to run code and drive browsers exactly as you ask — and the platform must guarantee that every session operates **fully independently**, even when code hits errors or contains vulnerabilities. A regular Kubernetes pod shares the host kernel — one kernel vulnerability can spread to other pods on the same node. With the sandbox, each session gets its own kernel, separated by a hardware-enforced virtualization boundary: an incident in one session stays inside that session. When the session ends, the VM is destroyed and all state inside it disappears.

---

## Connecting your agent

Each tool has its own MCP endpoint (streamable HTTP) behind the AgentBase Gateway. Connect using any MCP client (Claude Code, Cursor, or an MCP SDK):

| Tool | MCP endpoint |
|---|---|
| Code Interpreter | `https://gw-greennode-builtin-tools-110718.agentbase-gateway.aiplatform.vngcloud.vn/code` |
| Browser | `https://gw-greennode-builtin-tools-110718.agentbase-gateway.aiplatform.vngcloud.vn/browser` |

### Authentication

The endpoint is an **OAuth resource server** — your client drives the whole login flow, so you never create or paste tokens by hand:

1. The client calls the endpoint without a token → gets `401` with a `WWW-Authenticate` header pointing to the authorization server.
2. The client registers itself (**Dynamic Client Registration**) and opens the browser at the GreenNode Portal login URL.
3. After sign-in, the client keeps the access token and **refreshes it automatically** — no re-login every session.

Tokens from a **Root user, IAM user, or Service Account** all work — all three issue the same kind of access token. If your agent runs headless (no browser available), attach the access token directly in your client's configuration.

See each tool's page for detailed connection instructions.

---

## Getting Started with Built-in Tools

| I want to... | Go to |
|---|---|
| Let my agent run Python / shell | [Use Code Interpreter](use-code-interpreter.md) |
| Let my agent drive a browser, watch live, and replay recordings | [Use Browser](use-browser.md) |
| Understand the isolation, security model, and limits | [Sandbox: security and limits](sandbox-security-and-limits.md) |
83 changes: 83 additions & 0 deletions English/ai-stack/agent-base/built-in-tools/sandbox-security-and-limits.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,83 @@
# Sandbox — Security and Limits

## Isolation model

| Boundary | What it provides |
|---|---|
| microVM per session | Dedicated kernel, processes, filesystem, and memory. State from one session is never visible to another and is destroyed when the session is deleted. Uses Kata Containers + Cloud Hypervisor |
| Namespace per user | All VMs of one user live in a dedicated namespace (`agent-core-<userId>`), attached by the platform — callers cannot set or override it |
| Authentication at the gateway | Only valid tokens of the resource owner pass the gateway; downstream hops trust the tenant information attached by the gateway |
| Credential stripping | `Authorization`, `Cookie`, and identity headers are removed before a request reaches the VM; no service-account token is ever mounted into a sandbox pod |
| Dedicated vKS node group | Sandbox workloads run on a dedicated node group with nested virtualization enabled and the `nested-virt=true:NoSchedule` taint; sandbox pods run through RuntimeClass `kata-clh` |

## Credentials inside the sandbox

| Topic | Behavior |
|---|---|
| Caller's token | Never reaches the VM — stripped at the gateway/runtime before relay |
| Platform's internal tokens | Not mounted into sandbox pods; the tool service signs its own short-lived JWTs when calling into the runtime |
| Credentials for your agent | If the agent inside the sandbox needs credentials, pass them through your own channel — not via default headers |
| Vault credential | Roadmap: OpenSandbox's credential vault feature is not integrated in the current release |

## Network

| Flow | Allowed? |
|---|---|
| Inbound: from the gateway and sandbox management | Yes |
| Outbound: DNS, telemetry collector | Yes |
| Outbound: public internet | Yes |
| Outbound: private IP ranges (RFC 1918), metadata service, Kubernetes API server | No — blocked by a deny network policy |

## Limits and quotas

| Limit | Value | Notes |
|---|---|---|
| Code Interpreters per user | 5 (default) | Recorded into the quota row on first use |
| Browsers per user | 5 (default) | Counted per tool type |
| Total sessions per user | 10 (default) | Summed across all tools — sessions are what actually bounds resources |
| Session creation time (warm VM) | ~3 seconds | |
| Session creation time (cold VM boot) | ~17 seconds | Burst beyond the warm pool |
| First tool creation time | a few minutes | The VM pool must be provisioned and the first VM booted |
| One proxy call (including streaming) | 10 minutes | Exceeding returns `504` |
| Synchronous shell command | 30 seconds | Use `startCommandExecution` for longer work |
| Background command | 15 minutes | Fetch the result via `getTask` |
| File size per read/write | 10 MiB | Exceeding returns `413`; one file per call |
| Recording size | 64 MiB | Larger recordings are not stored |
| Sessions per endpoint | under 100 | Including warm VMs in the pool |
| Concurrent HTTP proxy calls service-wide | 25 | Shared across all callers; exceeding returns `503` |
| Concurrent WebSocket proxies service-wide | 25 | Exceeding closes with code `1013` |
| WebSocket idle / message size | 5 minutes / 1 MiB | |
| Session TTL / idle timeout | None | A session only ends when deleted |

{% hint style="warning" %}
There is no automatic session cleanup: a forgotten session keeps its VM and holds a quota slot until it is deleted or the tool is deleted. Always delete sessions when done.
{% endhint %}

## Resource statuses

| Status | Description |
|---|---|
| `CREATING` | Provisioning the VM pool and booting the first VM |
| `ACTIVE` | Ready to create sessions and invoke tools |
| `FAILED` | Timed out during creation — terminal status |
| `DELETED` | Deleted, quota returned |

## Common error codes

| Code | Meaning |
|---|---|
| `401` | Not signed in or token expired — re-run your MCP client's login flow |
| `404` | Resource does not exist — or belongs to another user (existence is not revealed) |
| `409` | Resource not yet `ACTIVE` when calling session/invoke |
| `413` | File exceeds the size limit |
| `429` / `503` | Platform busy or over the concurrent-call limit — retry later |
| `502` / `504` | Sandbox infrastructure error/timeout; call exceeded the 10-minute limit |

## Roadmap

| Topic | Status |
|---|---|
| Vault credential for sandbox | Not integrated yet (upstream OpenSandbox feature) |
| Custom sandbox runtime (own image, direct session API) | Internal only, not publicly available yet — pending the billing model |
| Session TTL / auto-cleanup | Under consideration (TTL or a reaper job) |
| Languages other than Python for `executeCode` | Roadmap |
122 changes: 122 additions & 0 deletions English/ai-stack/agent-base/built-in-tools/use-browser.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,122 @@
# Use Browser

> Connect your agent to **Browser** — drive a real Chrome inside a microVM dedicated to each session: automation over CDP, live screen view, and session recordings, integrated over MCP.

---

## Prerequisites

- A GreenNode account, and having completed [Getting Started with AgentBase](../getting-started.md)
- An account enabled in the Built-in Tools whitelist — see [Built-in Tools](README.md) if not yet enabled
- An agent with MCP client support (Claude Code, Cursor, or an MCP SDK)
- If your agent does its own automation: a **Chrome DevTools Protocol (CDP)** client — Playwright, Puppeteer, or any CDP client

---

## Connecting over MCP

**Step 1:** Get the Browser MCP endpoint:

```
https://gw-greennode-builtin-tools-110718.agentbase-gateway.aiplatform.vngcloud.vn/browser
```

**Step 2:** Add it to your MCP client configuration. Example for Claude Code:

```bash
claude mcp add --transport http browser \
https://gw-greennode-builtin-tools-110718.agentbase-gateway.aiplatform.vngcloud.vn/browser
```

Or for Cursor / VS Code — only `url` is needed:

```json
{
"mcpServers": {
"browser": {
"url": "https://gw-greennode-builtin-tools-110718.agentbase-gateway.aiplatform.vngcloud.vn/browser"
}
}
}
```

**Step 3:** Sign in the first time — your client runs the login flow itself (**Dynamic Client Registration**) and opens the GreenNode Portal login URL in the browser; the access token is kept and **refreshed automatically** afterwards. Tokens from a **Root user, IAM user, or Service Account** all work.

---

## How it works

Each **session** is a real Chrome browser running inside its own microVM. There are three separate streams:

```
Agent ──── automation stream (CDP, port 9222) ─────┐
Viewer ─── live view (noVNC, port 6080) ───────────┤── Chrome inside the microVM
Recording ─ saved when the session is deleted ─────┘
```

- **Automation stream** — your agent drives Chrome: the service relays your CDP connection to Chrome's debug port inside the VM. Playwright / Puppeteer work as if on localhost.
- **Live view** — a human watches Chrome's screen live over noVNC, embedded in the portal via an iframe.
- **Recording** — a session recording is preserved when the session ends.

Browser follows the same pattern as [Code Interpreter](use-code-interpreter.md): create the resource, wait for `ACTIVE`, create sessions (one VM per session), delete when done.

---

## Driving Chrome with the automation stream

**Step 1:** Create a Browser and a session (same as Code Interpreter: create → wait for `ACTIVE` → create session).

**Step 2:** Enable the automation stream for the session (tool / API `PUT .../sessions/{sessionId}/streams`). The stream can be toggled per session.

**Step 3:** Point your CDP client (Playwright, Puppeteer) at the session's automation stream address. The service relays your connection to Chrome inside the VM and rewrites the debugger address to point back at itself.

---

## Watching live (live view)

Chrome's screen is served over noVNC and embedded in the portal via an iframe. Because iframes and WebSockets cannot carry authentication headers, live view uses a **signed URL** (like a presigned URL):

1. The portal requests a signed live-view URL for the session (ticket valid for **5 minutes**).
2. The URL is placed in the `iframe src` — the ticket travels in the WebSocket path and is stripped before reaching the VM.
3. An established connection is not re-authenticated; each connection lives at most **1 hour**. On expiry, the portal signs a new URL and reloads the iframe.

---

## Recordings

The recording file lives inside the VM and would be lost when the VM is destroyed. Therefore, **when you delete a session**, the service reads the recording file just before the VM is destroyed and stores it on object storage. You can then fetch it with `GET .../sessions/{sessionId}/recording`.

{% hint style="warning" %}
Recording is **best effort**: if the file cannot be read or stored, the session deletion still proceeds and no recording is kept. Recordings larger than 64 MiB (default configuration) are not stored.
{% endhint %}

---

## Main API

| Path under `/v1/browsers` | Purpose |
|---|---|
| `POST`, `GET`, `GET /{id}`, `DELETE /{id}` | Create, list, view, delete a Browser |
| `POST/GET/DELETE /{id}/sessions[/{sessionId}]` | Manage sessions — each session is one Chrome in one VM |
| `PUT /{id}/sessions/{sessionId}/streams` | Enable/disable the automation stream |
| `/{id}/sessions/{sessionId}/automation-stream[/*]` | CDP relay, all methods |
| `POST .../live-view-stream-sign` and `GET .../live-view-stream[/*]` | Sign a live-view URL, and the view stream |
| `GET .../recording` | Fetch the stored recording |

---

## Deleting

1. Delete the session — the service saves the recording (if enabled), then destroys the VM and all state.
2. Delete the Browser when no longer needed — this returns the quota.

---

## Result

Your agent can drive a real Chrome (CDP), you can watch the screen live in the portal, and you can download the session recording after it ends.

| I want to... | Go to |
|---|---|
| Let my agent run Python / shell | [Use Code Interpreter](use-code-interpreter.md) |
| See all limits and the security model | [Sandbox: security and limits](sandbox-security-and-limits.md) |
Loading
Loading