No more setup headaches. Join a Network Automation project and start coding services immediately - not after days of wrestling with scattered docs, mismatched libraries, and broken sources.

This project provides:

• 🤝 Consistent environments - Same NSO versions, NEDs, and packages for the entire team
• 🚀 Build once, use many - Download artifacts once, spin up unlimited containers
• 🚢 Based on official NSO - Extends the official container image without modifying it

*The ncs.conf separates artifacts (/opt/ncs/packages) from your services (/nso/run/packages) for a clean development experience.

Set up your containerized NSO instance with all required NEDs and packages.

• Docker & Docker Compose
• Make
• Linux-based environment (this project doesn't support Windows)

git clone https://github.com/ponchotitlan/nso-consistent-dev-environment.git
cd nso-consistent-dev-environment

💡 Skip this if you already have a commercial NSO image.

Download the NSO Production Docker Image for Free Trial from Cisco Software Central:

# Unpack the signed file
sh nso-6.5-freetrial.container-image-prod.linux.x86_64.signed.bin

# Load into Docker
docker load < nso-6.5.container-image-prod.linux.x86_64.tar.gz

# Verify
docker images | grep cisco-nso-prod

Edit config.yaml to specify:

# NSO base image (from docker images)
nso-base: cisco-nso-prod:6.5
nso-image: my-nso-custom-dev
nso-name: my-nso-dev

# CXTA (optional test automation)
cxta-base: dockerhub.cisco.com/cxta-docker/cxta:latest
cxta-name: my-cxta-dev

# NEDs and packages to download
downloads:
  - https://example.com/path/to/resource-manager.tar.gz
  - https://example.com/path/to/cisco-nx-ned.tar.gz
  - https://example.com/path/to/cisco-iosxr-ned.tar.gz

# Packages that don't need compilation
skip-compilation:
  - resource-manager
  - cisco-iosxr-cli-7.69

# Netsim devices to create
netsims:
  cisco-iosxr-cli-7.69:
    - asr9k-xr-7601
    - ncs5k-xr-5702
  cisco-nx-cli-5.27:
    - nexus-9000-01

One command does everything:

make

This single command:

1. ✨ Renders configuration templates
2. 📤 Sets up local registry (if needed)
3. 🏗️ Builds custom NSO image with your artifacts
4. 🚀 Starts NSO and CXTA containers
5. 🛠️ Compiles your packages
6. 🔀 Reloads NSO services
7. 🛸 Creates and onboards netsim devices

Done! Your NSO environment is ready.

# Check containers
docker ps

# Check packages
docker exec my-nso-dev /bin/bash -c "echo 'show packages package * oper-status | tab' | ncs_cli -Cu admin"

# Check devices
docker exec my-nso-dev /bin/bash -c "echo 'show devices list' | ncs_cli -Cu admin"

If you prefer step-by-step control:

VSCode Users: Use the built-in task Terminal > Run Task > Open NSO Container

Command Line:

docker exec -it my-nso-dev /bin/bash

NSO CLI:

docker exec -it my-nso-dev ncs_cli -Cu admin

WebUI: http://localhost:8080

Set up VSCode and Python tools for professional NSO service development with AI assistance.

• ✅ Automated code quality - Format, lint, and type-check automatically
• ✅ AI-assisted coding - GitHub Copilot configured for NSO best practices
• ✅ Consistent style - Entire team follows the same standards
• ✅ Isolated environment - Python virtual environment avoids conflicts

One command installs everything:

make dev-setup

This creates a virtual environment (.venv) and installs:

• black - Code formatter
• isort - Import organizer
• mypy - Type checker
• pylint - Code linter

code --install-extension ms-python.python
code --install-extension njpwerner.autodocstring
code --install-extension GitHub.copilot

Or install manually from VSCode Extensions marketplace.

VSCode will automatically use the virtual environment and apply settings from .vscode/settings.json.

Full list available 🔗in this file.

✅ my-vpn-service-cfs (customer-facing)
✅ vlan-config-rfs (resource-facing)
❌ my-service (missing suffix)

def configure_device(device: str, config: dict) -> bool:
    """Configure device with parameters."""
    pass

def create_service(name: str, params: dict) -> None:
    """Create a new NSO service.
    
    Args:
        name: Service instance name
        params: Service parameters
        
    Raises:
        ValueError: If name is invalid
    """
    pass

# 1. One-time setup (first time only)
make dev-setup

# 2. Write code with GitHub Copilot assistance

# 3. Run quality checks before committing
make dev-check

# 4. Fix formatting issues automatically
make dev-format

# 5. Commit your changes
git add .
git commit -m "Add feature"

💡 All commands automatically use the virtual environment - no need to activate it manually!

Copilot is pre-configured via .github/copilot-instructions.md to:

• Suggest properly typed and documented code
• Add -cfs or -rfs suffixes to service names
• Follow Google-style docstrings
• Use NSO best practices

Just start typing and Copilot will guide you!

Always use ncs-make-package inside the NSO container:

# Wrong ❌
touch my-service.py

# Correct ✅
docker exec -it my-nso-dev /bin/bash
cd /nso/run/packages
ncs-make-package --service-skeleton python my-service-cfs

GitHub Copilot will remind you to use this command if you try to create files manually.

Container won't start or fails health check?

Known issue on Mac M-series chips with NSO v6.5. Solutions:

# Option 1: Retry
make down
make run

# Option 2: Check logs
docker logs -f my-nso-dev

# Option 3: Use Linux VM/cloud instance (recommended)

Container taking too long?

Large packages slow down initial boot. Monitor progress:

docker logs -f my-nso-dev

Quality checks failing?

make dev-check      # See detailed errors
make dev-format     # Auto-fix formatting

VSCode not recognizing settings?

1. Restart VSCode after make dev-setup
2. Check Python interpreter is .venv/bin/python (bottom-left in VSCode)
3. Verify .vscode/settings.json exists

Virtual environment issues?

make dev-clean      # Remove everything
make dev-setup      # Start fresh

• Cisco NSO Documentation
• Service Development Guide
• DEVNET-2224: DevOps for NSO

Made with ☕️ by Poncho Sandoval - Developer Advocate 🥑 @ DevNet - Cisco Systems 🇵🇹