`grn agentbase` Reference

grn agentbase is the subcommand tree of the greennode-cli for the GreenNode AgentBase platform — the set of backend services that let you create and operate agents on VNG Cloud. It ships in the default grn binary and the public release build — no special build tag is required.

grn agentbase --help

Overview

Breaking change: grn agentbase identity → grn agentbase access; identity workload → access agent-id; grn agentbase catalog → grn agentbase marketplace. Old names are removed (no aliases). Update any scripts.

The AgentBase platform is served behind agentbase.api.vngcloud.vn (prod) / agentbase.api-dev.vngcloud.tech (dev), plus a client-side orchestrator, deploy:

Command group	Role
`access`	Manage agent digital identities + outbound auth (OAuth2/API key)
`gateway`	Create/manage MCP gateways (provision VKS runtime, DNS, load balancer, quota)
`runtime`	Deploy the container that runs the agent code (image/command/args/env/autoscaling)
`marketplace`	Browse the marketplace: runtime flavors, OpenClaw versions + workspaces
`memory`	Long-term memory for agents (Mem0 vector store, semantic search)
`tools`	Built-in tools agents invoke: headless browsers + code interpreters (dev-only service)
`policy`	Cedar policy engine (policy-groups + policies + decision)
`cr`	Wrapper for VNG Cloud Container Registry (vCR): auto-provisioned repo + robot account
`deploy`	Orchestrator composing access + memory + runtime (+ cr)
`context`	Show the active environment + endpoints

An agent is the set of resources that share a name (the join key): an agent identity (always present), an optional memory container (omit for a stateless agent), and a runtime (the container that runs the agent code). There is no cross-service foreign key; deploy uses the name as the join.

Setup & authentication

agentbase shares the ~/.greennode profile with the rest of grn (vks/vserver) — there is no separate .greennode.json file. There are two auth modes:

Machine mode (M2M) — recommended for CI

grn configure --profile default
# Enter client_id (GRN_CLIENT_ID) and client_secret (GRN_CLIENT_SECRET)

The CLI uses clientcredentials to mint an IAM v2 token. The client_secret is never baked into the binary or logged; the refresh_token is stored at rest (0600, masked in configure list/get).

User mode (PKCE) — recommended for interactive use

grn login --iam-env prod          # PKCE login
grn logout                        # clear the login

The active mode is determined by auth_mode in the profile (user or machine). All three services (vks/vserver/agentbase) use a single shared token selector.

Choosing the environment (dev / prod)

The environment is selected via iam_env in the profile (default prod).

# Shared with vks/vserver:
grn configure set iam_env <dev|prod>     # (machine)
grn login --iam-env <dev|prod>           # (user)

# Show the active environment + endpoints:
grn agentbase context current

Note: in user mode, iam_env is bound to the login token. To switch environments, you must grn login --iam-env <env> again. In machine mode, iam_env can be switched freely.

Overriding endpoints (`--endpoint-url`)

The global --endpoint-url flag repoints every agentbase service endpoint (identity/runtime/memory/gateway/policy/cr) at a different host, preserving each service's path segment so routing still works — e.g. --endpoint-url https://agentbase-staging.example.com sends identity calls to …/identity, runtime to …/runtime, and so on. The IAM token URL (OAuth2 Token in context current) is not overridden; it stays on iam_env. The same endpoint-safety policy as vks applies (trusted-domain / TLS check, --allow-untrusted-endpoint to force).

grn --endpoint-url https://agentbase-staging.example.com agentbase access agent-id list

Command reference

All commands accept the common flags -o json|table|id (output format) and --interactive (prompt for missing required parameters).

Command group	Description
context	Show the active environment + standard headers/decorators
access	Agent identities + outbound auth (OAuth2 / static API key / delegated)
gateway	Create/manage MCP gateways (async FSM; use `wait` to converge)
runtime	Deploy the agent container (image/command/args/env/autoscaling)
memory	Long-term memory container (Mem0 vector store, semantic search)
marketplace	Runtime placement flavors + OpenClaw versions/workspaces
tools	Built-in tools: headless browsers + code interpreters (sessions, streams, invoke + task-wait)
policy	Cedar policy engine (policy-groups + policies + decision)
cr	VNG Cloud Container Registry wrapper (auto-provisioned repo + robot account)
deploy	Client-side orchestrator (access + memory + runtime + cr)

Output format

Every command takes -o (--output):

Value	Meaning
`table` (default)	Human-readable table; secrets masked
`json`	Raw JSON — secrets revealed (e.g. to pipe into `docker login`)
`id`	Print only the ID (for scripting)

When -o/--output is not passed, the format falls back to the output key in ~/.greennode/config (the same fallback vks/vserver use), then to table. So grn configure set output json governs grn agentbase too. (context current uses a fixed table layout and is not affected by the output format.)

grn's global --query (a JMESPath expression filtering the output) works with agentbase commands only with -o json; with table/id it fails fast with an error instead of being silently ignored.

Paging envelope reference

Each service uses a different pagination shape — a common source of confusion:

Service	Envelope	`size` query key
gateway	`{items, pagination}`	—
runtime	`{listData, page, pageSize, totalPage, totalItem}`	`size`
memory	`{listData, page, pageSize, totalPage, totalItem}`	`size`
tools	`{listData, page, pageSize, totalPage, totalItem}`	`size`
policy	`{content, page, pageSize, totalPage, totalItem}`	`page_size` (snake)
cr	`{data, page, pageSize, totalItem, totalPage}`	`size`
access	`{content, page, size, totalElements, totalPages, ...}`	`size`

Troubleshooting

authentication failed: ... — run grn configure (machine) or grn login (user). Check grn agentbase context current for env/profile.
404 on lookup — deploy/status look up by name via List + filter; a wrong name or a resource in a different environment reports as absent.
runtime stuck in CREATING — runtimes converge asynchronously; use grn agentbase runtime wait <id> (or deploy status <name>) to wait.
Switching dev↔prod — machine: grn configure set iam_env <env>; user: grn login --iam-env <env> (must re-login, since the token is bound to env).

grn agentbase Reference