# Send SONiC KVM Testbed to your agent
Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.
## Fast path
- Download the package from Yavira.
- Extract it into a folder your agent can access.
- Paste one of the prompts below and point your agent at the extracted folder.
## Suggested prompts
### New install

```text
I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete.
```
### Upgrade existing

```text
I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run.
```
## Machine-readable fields
```json
{
  "schemaVersion": "1.0",
  "item": {
    "slug": "sonic-kvm-testbed",
    "name": "SONiC KVM Testbed",
    "source": "tencent",
    "type": "skill",
    "category": "开发工具",
    "sourceUrl": "https://clawhub.ai/yxieca/sonic-kvm-testbed",
    "canonicalUrl": "https://clawhub.ai/yxieca/sonic-kvm-testbed",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadUrl": "/downloads/sonic-kvm-testbed",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=sonic-kvm-testbed",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "packageFormat": "ZIP package",
    "primaryDoc": "SKILL.md",
    "includedAssets": [
      "SKILL.md",
      "references/credentials.md",
      "references/troubleshooting.md"
    ],
    "downloadMode": "redirect",
    "sourceHealth": {
      "source": "tencent",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-05-07T17:22:31.273Z",
      "expiresAt": "2026-05-14T17:22:31.273Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=afrexai-annual-report",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=afrexai-annual-report",
        "contentDisposition": "attachment; filename=\"afrexai-annual-report-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null
      },
      "scope": "source",
      "summary": "Source download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this source.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/sonic-kvm-testbed"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    }
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/sonic-kvm-testbed",
    "downloadUrl": "https://openagent3.xyz/downloads/sonic-kvm-testbed",
    "agentUrl": "https://openagent3.xyz/skills/sonic-kvm-testbed/agent",
    "manifestUrl": "https://openagent3.xyz/skills/sonic-kvm-testbed/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/sonic-kvm-testbed/agent.md"
  }
}
```
## Documentation

### SONiC KVM Virtual Testbed

Deploy a local sonic-mgmt KVM testbed with cEOS neighbors on a single machine.

### Architecture

Host Machine (KVM + Docker)
├── vlab-XX (KVM VM running sonic-vs) — DUT
├── ceos_vmsX-Y_VMZZ (Docker) — cEOS neighbor(s)
├── ptf_vmsX-Y (Docker) — PTF test traffic generator
└── sonic-mgmt (Docker) — Ansible + pytest framework

Management network: br1 bridge, 10.250.0.0/24 (host at .1).

### Supported Topologies

Testbed NameTopoDUTVM BaseNeighbors (raw → converged)vms-kvm-t0t0vlab-01VM01004 → 1 cEOSvms-kvm-t1-lagt1-lagvlab-03VM010424 → 2 cEOS

Use use_converged_peers: true in vtestbed.yaml to reduce cEOS containers via multi-VRF convergence (requires PR #22399 in master branch).

### Prerequisites

Ubuntu 20.04/22.04/24.04, KVM enabled (kvm-ok)
30GB+ RAM (for single topo) or 20GB+ with reduced VM memory
Docker installed, user in docker, kvm, libvirt groups
Built sonic-vs.img.gz from sonic-buildimage
cEOS image file (e.g., cEOS64-lab-4.32.5M.tar.xz)
sshpass installed on host

### 1. Initial Setup (one-time)

# Clone repo
git clone https://github.com/sonic-net/sonic-mgmt.git ~/sonic-mgmt
cd ~/sonic-mgmt && git checkout master  # PR #22399 needed for auto-convergence

# Prepare images
mkdir -p ~/veos-vm/images ~/sonic-vm/images
gunzip -k sonic-vs.img.gz
cp sonic-vs.img ~/veos-vm/images/ && cp sonic-vs.img ~/sonic-vm/images/

# Import cEOS (docker import, NOT docker load)
xz -d cEOS64-lab-4.32.5M.tar.xz
docker import cEOS64-lab-4.32.5M.tar ceosimage:4.32.5M

# Management bridge
cd ~/sonic-mgmt/ansible && sudo ./setup-management-network.sh

# debian:jessie dependency
docker pull publicmirror.azurecr.io/debian:jessie
docker tag publicmirror.azurecr.io/debian:jessie debian:jessie

# sonic-mgmt container
./setup-container.sh -n sonic-mgmt -d /data

# Create vault password file
echo "abc" > ~/sonic-mgmt/ansible/password.txt

### 2. Configure Credentials and Settings

See references/credentials.md for all config files.

Critical files (these reset on git operations — automate fixes in a script):

FileKey SettingWhygroup_vars/vm_host/creds.ymlvm_host_user: <your_user>Host SSH accessgroup_vars/all/creds.ymlsonic_login: "<dut_user>"DUT SSH user (matches sonic-vs build user)group_vars/all/ceos.ymlskip_ceos_image_downloading: trueUse local cEOS imagegroup_vars/vm_host/main.ymlmax_fp_num: 127Default 4 is too low for T0/T1veos_vtbansible_user: <your_user>Inventory host userveosComment out STR-ACS-SERV-01Avoid dual-host conflictvars/docker_registry.ymlRemove :443 from host:443 causes docker pull to hangvtestbed.yamluse_converged_peers: trueEnable multi-VRF convergence

Create a fix script to re-apply all settings. Run it before EVERY testbed operation.

### 3. Deploy Topology

# Fix configs + remove stale .bak
bash fix-configs.sh
rm -f vars/topo_<TOPO>.yml.bak

# Inside sonic-mgmt container:
./testbed-cli.sh -t vtestbed.yaml add-topo <TESTBED_NAME> password.txt

Duration: ~15-20 minutes (VM boot + cEOS startup).

### 4. Post-Deploy DUT Setup

After add-topo, the DUT boots with the build user. The multi_passwd_ssh plugin expects admin:

# SSH to DUT as build user
ssh <build_user>@<DUT_IP>

# Create admin user
sudo useradd -m -s /bin/bash -G sudo,docker admin
echo 'admin:password' | sudo chpasswd
sudo bash -c "echo 'admin ALL=(ALL) NOPASSWD:ALL' > /etc/sudoers.d/admin"

# Fix docker socket
sudo chmod 666 /var/run/docker.sock

### 5. Deploy Minigraph

# Fix configs + remove .bak AGAIN (they revert!)
bash fix-configs.sh
rm -f vars/topo_<TOPO>.yml.bak

./testbed-cli.sh -t vtestbed.yaml deploy-mg <TESTBED_NAME> veos_vtb password.txt

Duration: ~5-10 minutes.

### 6. Verify

# Check containers
docker ps | grep -E "ceos|ptf"

# Check BGP (use admin after deploy-mg)
sshpass -p password ssh admin@<DUT_IP> "show ip bgp summary"

Expected BGP state with converged peers:

T0: ARISTA01T1 Established (6400 prefixes), ARISTA02-04T1 Active (normal — VRF peers without physical port-channels)
T1-LAG: 17/24 sessions up (all T0 + 1 T2 spine; remaining T2 spines Active)

### 7. Run Tests

cd /data/sonic-mgmt/tests
./run_tests.sh -n <TESTBED_NAME> -d <DUT_NAME> -c <test_path> \\
  -f vtestbed.yaml -i ../ansible/veos_vtb

### Teardown

bash fix-configs.sh
rm -f vars/topo_<TOPO>.yml.bak
./testbed-cli.sh -t vtestbed.yaml remove-topo <TESTBED_NAME> password.txt

Duration: ~12-15 minutes.

### Critical Gotchas

Config files revert during git and testbed operations — run fix script before EVERY command
Remove .bak files before add-topo — stale backups cause KeyError in converger
docker import for cEOS (not docker load)
:443 in docker_registry_host silently hangs docker pulls
max_fp_num: 4 is too low — set to 127
br1 bridge is not persistent across reboots — add netplan config
Non-admin builds: sonic-vs uses the build machine's username, not admin
use_converged_peers: true requires master branch (PR #22399) for auto-convergence

### Troubleshooting

See references/troubleshooting.md for detailed diagnosis of common failures.
## Trust
- Source: tencent
- Verification: Indexed source record
- Publisher: yxieca
- Version: 1.2.0
## Source health
- Status: healthy
- Source download looks usable.
- Yavira can redirect you to the upstream package for this source.
- Health scope: source
- Reason: direct_download_ok
- Checked at: 2026-05-07T17:22:31.273Z
- Expires at: 2026-05-14T17:22:31.273Z
- Recommended action: Download for OpenClaw
## Links
- [Detail page](https://openagent3.xyz/skills/sonic-kvm-testbed)
- [Send to Agent page](https://openagent3.xyz/skills/sonic-kvm-testbed/agent)
- [JSON manifest](https://openagent3.xyz/skills/sonic-kvm-testbed/agent.json)
- [Markdown brief](https://openagent3.xyz/skills/sonic-kvm-testbed/agent.md)
- [Download page](https://openagent3.xyz/downloads/sonic-kvm-testbed)