/nebius — Nebius AI Cloud CLI Skill

You are an expert at deploying and managing infrastructure on Nebius AI Cloud using the nebius CLI.

When to Use This Skill

Always use for:

• Any mention of "nebius", Nebius services, or Nebius-specific terms (mk8s, soperator, token factory)
• Generic deployment requests: "deploy this app", "deploy my model", "spin up a server", "make this live"
• GPU/inference requests: "I need a GPU", "deploy this LLM", "create an inference endpoint", "host this model"
• Generic infrastructure: "create a VM", "set up kubernetes", "I need a container registry", "set up a database"
• Serverless requests: "make this serverless", "deploy as an endpoint", "create an API endpoint for this"

Do NOT use when:

• Another cloud provider is explicitly named (AWS, GCP, Azure, DigitalOcean, etc.)
• The task is purely local (docker compose, dev servers, localhost)
• The task is non-infrastructure (code review, debugging, file editing, CI/CD config)

Pre-flight Check

Before running ANY nebius commands, verify the CLI is installed and authenticated:

bash ${CLAUDE_SKILL_DIR}/scripts/check-nebius-cli.sh

If the check fails, follow the three setup steps below.

Step 1. Install the Nebius CLI

curl -sSL https://storage.eu-north1.nebius.cloud/cli/install.sh | bash
exec -l $SHELL   # reload shell so 'nebius' is on PATH
nebius version    # confirm installation

Step 2. Create a profile and authenticate

nebius profile create
# Follow the interactive prompts:
#   - Profile name (press Enter for "default")
#   - Accept defaults for endpoint and federation
#   - A browser window opens — log in with your Nebius account

If your token expires later, re-authenticate by re-running nebius profile create (reopens browser login).

Step 3. Get your IAM access token

For non-interactive / headless environments (CI/CD, containers, Claude Code on the web),

the user must provide their IAM token. They can obtain it on their local machine:

nebius iam get-access-token

Then pass it to the headless environment:

export NEBIUS_IAM_TOKEN="<paste-token-here>"

> Important: The IAM token (from nebius iam get-access-token) is for Nebius Cloud CLI operations

> (creating endpoints, VMs, etc.). This is different from the Token Factory API key (starts with v1.),

> which is used for model inference inside your deployed container.

Finding your project ID

If your profile does not have a parent-id set:

# List projects (requires tenant-id in your profile, or pass it explicitly):
nebius iam project list --format json | jq -r '.items[] | {id: .metadata.id, name: .metadata.name, region: .status.region}'
# Set the project:
nebius config set parent-id <PROJECT_ID>

Validate connectivity (quick smoke test)

nebius iam whoami --format json
nebius ai endpoint list --format json  # Should return empty list or endpoints

Key Conventions

• Always use --format json when running nebius commands programmatically. Parse output with jq.
• Check before creating — use list commands to see if a resource already exists before creating a duplicate.
• Region awareness — eu-west1 uses cpu-d3 (not cpu-e2). Always confirm which region the user is targeting.
• Disk types use underscores — network_ssd, NOT network-ssd. Also network_hdd, network_ssd_io_m3.
• Image family flag — use --source-image-family-image-family (double "image-family"), NOT --source-image-family.
• Minimum disk size — ubuntu22.04-cuda12 requires at least 50 GiB. Using 30 GiB will fail.
• Multiple container ports — use --container-port 8080 --container-port 18789 to expose both health + dashboard.
• SSH username is nebius — not root, ubuntu, admin, or user. This is the default for Nebius VMs and endpoints.
• Public IP includes /32 suffix — strip it: jq -r '.status.network_interfaces[0].public_ip_address.address' | cut -d/ -f1.

Core Services

1. Serverless AI Endpoints (Most Common Use Case)

Deploy ML models or agent containers as auto-scaling serverless endpoints.

For detailed commands and parameters, see references/ai-endpoints-reference.md.

Quick deploy (CPU-only, uses Token Factory for inference):

WEB_PASSWORD=$(openssl rand -base64 24)
nebius ai endpoint create \
  --name my-endpoint \
  --image <REGISTRY_IMAGE> \
  --platform cpu-e2 \
  --container-port 8080 \
  --container-port 18789 \
  --env "TOKEN_FACTORY_API_KEY=<key>" \
  --env "INFERENCE_MODEL=<model>" \
  --env "OPENCLAW_WEB_PASSWORD=${WEB_PASSWORD}" \
  --public
# SSH: nebius ai endpoint ssh <ENDPOINT_ID>
# Tunnel: ssh -f -N -L 28789:<PUBLIC_IP>:18789 nebius@<PUBLIC_IP>
# Dashboard: http://localhost:28789/#token=${WEB_PASSWORD}&gatewayUrl=ws://localhost:28789

GPU deploy (self-hosted inference):

nebius ai endpoint create \
  --name my-gpu-endpoint \
  --image <REGISTRY_IMAGE> \
  --platform gpu-h100-sxm \
  --preset 1gpu-16vcpu-200gb \
  --container-port 8080 \
  --disk-size 100Gi \
  --shm-size 16Gi \
  --public \
  --auth token \
  --token "<auth-token>"

2. Compute VMs

Create GPU or CPU virtual machines for training, development, or hosting.

For detailed commands, see references/compute-reference.md.

3. Managed Kubernetes (mk8s)

Create managed Kubernetes clusters with GPU node groups.

For detailed commands, see references/kubernetes-reference.md.

4. Container Registry

Build and push container images to Nebius Container Registry.

For detailed commands, see references/registry-reference.md.

5. Networking (VPC)

Create networks and subnets required by VMs and endpoints.

For detailed commands, see references/networking-reference.md.

6. IAM & Authentication

Manage service accounts, access keys, and project access.

For detailed commands, see references/iam-reference.md.

7. gRPC API & SDKs

For programmatic access beyond the CLI — application code, CI/CD pipelines, or infrastructure-as-code:

Quick Python example:

from nebius.sdk import SDK
from nebius.api.nebius.ai.v1 import EndpointServiceClient, ListEndpointsRequest
sdk = SDK()  # reads NEBIUS_IAM_TOKEN env var
svc = EndpointServiceClient(sdk)
endpoints = await svc.list(ListEndpointsRequest(parent_id=project_id))

For full SDK reference, authentication patterns, and all gRPC endpoints, see references/api-reference.md.

Available GPU Platforms

Regions

Common Presets

End-to-End Deployment Examples

For complete step-by-step deployment workflows, see:

• examples/deploy-openclaw.md - Deploy OpenClaw/NemoClaw to Nebius serverless (quickest path)
• examples/deploy-serverless-endpoint.md - Deploy a custom AI agent as a serverless endpoint
• examples/deploy-gpu-vm.md - Deploy a GPU VM with vLLM for self-hosted inference

OpenClaw / NemoClaw Deployment

OpenClaw is an open-source AI agent platform. NemoClaw is an NVIDIA security container that wraps OpenClaw, adding sandboxed execution and enhanced planning — ideal for GPU endpoints with local models.

Step-by-Step: Deploy OpenClaw to Nebius Serverless

When the user asks to deploy OpenClaw (or an AI agent), follow these steps:

Step 1. Choose image and model:

# OpenClaw (CPU, lightweight, Token Factory inference):
IMAGE="ghcr.io/colygon/openclaw-serverless:latest"
MODEL="zai-org/GLM-5"   # or: deepseek-ai/DeepSeek-R1-0528, MiniMaxAI/MiniMax-M2.5, zai-org/GLM-4.5

# NemoClaw (GPU, local model, NVIDIA security container):
IMAGE="ghcr.io/colygon/nemoclaw-serverless:latest"

Step 2. Get a Token Factory API key (if using Token Factory):

# Check if user has a key in MysteryBox:
nebius mysterybox secret list --format json | jq '.items[] | {name: .metadata.name, id: .metadata.id}'
# Retrieve key from MysteryBox:
nebius mysterybox payload get --secret-id <SECRET_ID> --format json | jq -r '.data[0].string_value'
# Or ask user for their key from https://tokenfactory.nebius.com

Step 3. Determine region, CPU platform, and Token Factory URL:

# eu-north1 (Finland) → cpu-e2    eu-west1 (Paris) → cpu-d3    us-central1 (US) → cpu-e2
REGION="eu-north1"
PLATFORM="cpu-e2"
PRESET="2vcpu-8gb"

# Token Factory URL — US region uses a different endpoint:
if [[ "$REGION" == "us-central1" ]]; then
  TOKEN_FACTORY_URL="https://api.tokenfactory.us-central1.nebius.com/v1"
else
  TOKEN_FACTORY_URL="https://api.tokenfactory.nebius.com/v1"
fi

Step 4. Generate a gateway password:

PASSWORD=$(openssl rand -hex 16)
echo "Dashboard password: $PASSWORD"  # Save this — needed to connect

Step 5. Create the endpoint (private IP by default):

By default, create endpoints without --public to avoid hitting the public IP quota (default: 3 per tenant).

The endpoint gets a private IP on the VPC subnet. You access it via nebius ai endpoint ssh.

nebius ai endpoint create \
  --name openclaw-agent \
  --image "$IMAGE" \
  --platform "$PLATFORM" \
  --preset "$PRESET" \
  --container-port 8080 \
  --container-port 18789 \
  --disk-size 250Gi \
  --env "TOKEN_FACTORY_API_KEY={user's key}" \
  --env "TOKEN_FACTORY_URL=${TOKEN_FACTORY_URL}" \
  --env "INFERENCE_MODEL=$MODEL" \
  --env "OPENCLAW_WEB_PASSWORD=$PASSWORD" \
  --public \
  --ssh-key "$(cat ~/.ssh/id_ed25519.pub 2>/dev/null || echo '')" \
  --format json

> Public IP quota: The default limit is 3 public IPs per tenant. Stopped endpoints with public IPs

> still consume quota. Delete unused endpoints with nebius ai endpoint delete to free IPs.

> You can omit --public for private-IP-only endpoints, but nebius ai endpoint ssh and direct SSH

> both require a public IP.

Step 6. Wait for RUNNING state:

# Poll until ready (typically 1-3 minutes):
nebius ai endpoint get <ENDPOINT_ID> --format yaml | grep -A5 'state\|private_ip\|public_ip'

Step 7. Access the endpoint terminal (SSH):

nebius ai endpoint ssh <ENDPOINT_ID>
# or: ssh -o StrictHostKeyChecking=no nebius@<PUBLIC_IP>

> Note: nebius ai endpoint ssh requires a public IP on the endpoint.

Once inside the endpoint, verify the container is healthy:

curl http://localhost:8080
# Expected: {"status":"healthy","service":"openclaw-serverless","model":"zai-org/GLM-5",...}

Step 8. Set up SSH tunnel for the dashboard:

From your local machine (not the endpoint), tunnel port 18789 through the endpoint:

ssh -f -N -o StrictHostKeyChecking=no -L 28789:<PUBLIC_IP>:18789 nebius@<PUBLIC_IP>

Step 9. Auto-approve device pairing (the gateway token must be passed or the approve command fails with "unauthorized"):

ssh -o StrictHostKeyChecking=no nebius@<PUBLIC_IP> \
  "sudo docker exec \$(sudo docker ps -q | head -1) \
   env OPENCLAW_GATEWAY_TOKEN=$PASSWORD openclaw devices approve --latest"

Step 10. Tell the user how to connect (always use localhost URLs, never direct IP):

• Dashboard: http://localhost:28789/#token=&gatewayUrl=ws://localhost:28789
• TUI: openclaw tui --url ws://localhost:28789 --token
• If the SSH tunnel dies: ssh -f -N -L 28789::18789 nebius@

Pre-built Public Images

Pre-built images are available on GitHub Container Registry (no build required):

# OpenClaw only (lightweight, ~400 MB, CPU)
ghcr.io/colygon/openclaw-serverless:latest

# NemoClaw (OpenClaw in NVIDIA security container, ~1.1 GB, GPU-ready)
ghcr.io/colygon/nemoclaw-serverless:latest

OpenClaw Nebius Provider Plugin

After deploying OpenClaw, you can install the Nebius provider plugin to give your agent access to 44+ open-source models (Qwen, DeepSeek, Llama, GLM, FLUX, and more) via Nebius Token Factory.

Install the plugin:

openclaw plugins install clawhub:@colygon/openclaw-nebius

Configure the API key (both locations needed):

# 1. Auth profile (for the agent) — edit ~/.openclaw/agents/main/agent/auth-profiles.json:
#    Add "nebius:default": { "type": "api_key", "provider": "nebius", "key": "v1.YOUR_KEY" }
#    Add "nebius": "nebius:default" under "lastGood"

# 2. Environment variable (for the gateway LaunchAgent):
launchctl setenv NEBIUS_API_KEY "v1.YOUR_KEY_HERE"

Enable and restart:

openclaw config set plugins.allow '["nebius"]'
openclaw gateway restart

Verify:

openclaw plugins inspect nebius
openclaw models list --provider nebius

Set default model (optional):

openclaw config set agents.defaults.model.primary "nebius/deepseek-ai/DeepSeek-V3.2"

Model naming: Always use the nebius/ prefix — nebius/zai-org/GLM-5 (correct), not zai-org/GLM-5 (will fail with "Unknown model").

Popular models: nebius/Qwen/Qwen3.5-397B-A17B, nebius/deepseek-ai/DeepSeek-V3.2, nebius/zai-org/GLM-5, nebius/openai/gpt-oss-120b. See the tokenfactory-plugin package for the full catalog and pricing.

Gateway Configuration (openclaw.json)

The entrypoint script generates ~/.openclaw/openclaw.json at container startup. Critical rules:

• Token must be in BOTH config file AND env var: Setting only the env var is unreliable after manual gateway restarts. The config file is the source of truth.

```json

"gateway": {

"auth": { "mode": "token", "token": "${OPENCLAW_GATEWAY_TOKEN}" }

}

```

• Map OPENCLAW_WEB_PASSWORD → OPENCLAW_GATEWAY_TOKEN: The deploy UI sets OPENCLAW_WEB_PASSWORD, but the gateway reads OPENCLAW_GATEWAY_TOKEN. The entrypoint must map them:

```bash

export OPENCLAW_GATEWAY_TOKEN="${OPENCLAW_WEB_PASSWORD:-${GATEWAY_TOKEN:-openclaw-$(hostname)}}"

```

• Do NOT add a plugins key: "plugins": { "nemoclaw": { "enabled": true } } is NOT a valid OpenClaw config key and crashes the gateway with "Config invalid - plugins: Unrecognized key". NemoClaw loads automatically when present in the container.
• allowedOrigins: ["*"]: Required for dashboard access through reverse proxies:

```json

"gateway": {

"controlUi": { "allowedOrigins": ["*"] }

}

```

• Model IDs must use Token Factory format: Use zai-org/GLM-5, NOT THUDM/GLM-4-9B-0414. Check available models: curl -s $TOKEN_FACTORY_URL/models -H "Authorization: Bearer $KEY" | jq '.data[].id'

Dashboard Access

• Expose the port: Use --container-port 18789 alongside --container-port 8080
• Set dashboard password: --env "OPENCLAW_WEB_PASSWORD="
• SSH tunnel required: Browsers block device identity without HTTPS or localhost. Set up a tunnel first:

```bash

ssh -f -N -o StrictHostKeyChecking=no -L 28789::18789 nebius@

```

• Dashboard URL format (always use localhost, never direct IP):

http://localhost:28789/#token=&gatewayUrl=ws://localhost:28789

• Token MUST be in the URL hash (#token=), NOT query string (?token=)
• gatewayUrl MUST accompany token or it becomes "pending" and is ignored
• Device pairing: Each new browser/TUI requires pairing approval. The gateway token must be passed as an env var or the command fails with "unauthorized":

```bash

ssh nebius@ "sudo docker exec \$(sudo docker ps -q | head -1) \

env OPENCLAW_GATEWAY_TOKEN= openclaw devices approve --latest"

```

Accessing the Endpoint Terminal

# Option A: Via Nebius CLI (requires public IP):
nebius ai endpoint ssh <ENDPOINT_ID>

# Option B: Direct SSH (requires public IP):
ssh -o StrictHostKeyChecking=no nebius@<PUBLIC_IP>

# Once inside, check the container:
sudo docker ps
sudo docker logs $(sudo docker ps -q | head -1) --tail 50
curl http://localhost:8080   # health check

TUI Connection

# 1. SSH tunnel (if not already set up for dashboard):
ssh -f -N -o StrictHostKeyChecking=no -L 28789:<PUBLIC_IP>:18789 nebius@<PUBLIC_IP>

# 2. Approve device pairing (first time only — must include gateway token):
ssh nebius@<PUBLIC_IP> "sudo docker exec \$(sudo docker ps -q | head -1) \
  env OPENCLAW_GATEWAY_TOKEN=<password> openclaw devices approve --latest"

# 3. Connect:
openclaw tui --url ws://localhost:28789 --token <password>

Note: Port 18789 on localhost may conflict with a local OpenClaw gateway. Use a different port (e.g., 28789).

Gateway Gotchas

• Config secrets are redacted: openclaw config get gateway.auth.token returns __OPENCLAW_REDACTED__. Read raw JSON: cat ~/.openclaw/openclaw.json
• Gateway refuses --auth none with --bind lan: Must use --auth token or --auth password
• SIGHUP kills the gateway: No graceful reload. Must restart manually after config changes.
• --force needs fuser/lsof: Minimal containers lack these. Start without --force if port is free.

Docker Build Notes (NemoClaw)

• Must use node:22 (not node:22-slim): NemoClaw's @whiskeysockets/baileys dependency needs build tools (python3, make, gcc) unavailable in slim.
• Use --ignore-scripts: npm install -g git+https://github.com/NVIDIA/NemoClaw.git --ignore-scripts — the baileys post-install script fails inside Docker BuildKit.
• Build on native amd64: Cross-compiling ARM → amd64 is very slow. Build on a Nebius VM for 5x faster builds.

Inference Providers

Token Factory is the default, but OpenRouter and HuggingFace also work (routed through Nebius GPUs):

Token Factory URLs by region:

• EU (eu-north1, eu-west1): https://api.tokenfactory.nebius.com/v1
• US (us-central1): https://api.tokenfactory.us-central1.nebius.com/v1

Common Gotchas

Troubleshooting

For full authentication options, see Nebius CLI docs and references/iam-reference.md.

Safety Rules

1. Always confirm before creating billable resources - GPU VMs and endpoints cost money. Show the user what will be created and estimated cost tier before proceeding.
2. Never delete without explicit confirmation - Always list what will be deleted and ask for confirmation.
3. Prefer --format json - Parse output programmatically to avoid errors.
4. Check existing resources first - Before creating, check if a resource with the same name already exists using list commands.
5. Suggest cost optimization - Recommend CPU-only (cpu-e2) for agent/orchestration workloads that don't need local GPU. Suggest stopping endpoints/VMs when not in use.