Overview The VM Agent (SecureVirtualizedAgent) is NikCLI’s second registered agent for autonomous development in isolated Docker environments. It provides secure, containerized development capabilities with complete repository management, API key proxy for zero secret exposure, and pull request automation.
This document describes the VM Agent , one of only two registered agents in NikCLI. Other specialized agents (React, Backend, Frontend, DevOps) exist as internal code modules but are not registered as separate agents - their functionality is handled by the Universal Agent through cognitive routing.
Isolated Execution Secure development in containerized environments
Repository Management Complete Git operations and repository analysis
Pull Request Automation Automated PR creation and management
Secure Communication API key proxying and token budget management
Core Capabilities The VM Agent provides 20 registered capabilities for virtualized development (expandable via configuration):
VM-Specific Capabilities (7)
vm-management - Docker container lifecycle managementcontainer-orchestration - Multi-container coordinationisolated-execution - Secure sandboxed code executionrepository-cloning - Automated Git repository setupvscode-server - Remote VS Code server integrationautonomous-development - Self-directed development workflowspull-request-automation - Automated PR creation and management
Repository Management (5)
repository-analysis - Deep codebase analysis and structure detectiondependency-management - NPM/Yarn/PNPM package managementtesting-automation - Automated test execution and reportingdocumentation-generation - Auto-generated code documentationcode-quality-analysis - Static analysis and quality metrics
Security Features (5)
secure-api-communication - API key proxy with zero secret exposuretoken-budget-management - 50,000 token budget enforcement per sessionaudit-logging - Complete activity audit trailresource-isolation - Container CPU/memory/disk limitscredential-management - Secure JWT-based session management
Development Workflows (3)
full-stack-development - Complete application development in containersci-cd-integration - GitHub Actions/GitLab CI integrationgit-operations - Full Git workflow automationpackage-management - Dependency installation and updatesenvironment-setup - Automated environment configuration
Resource Limits:
Token Budget: 50,000 tokens per session (enforced)
Concurrent Tasks: 1 task at a time
Container Timeout: 30 minutes default
Max Retries: 2 attempts
Usage Examples VM Container Operations Create VM Container
Container Management
Development Tasks
# Create new VM container from repository /vm-create https://github.com/user/repo.git # Create VM with specific configuration /vm-create https://github.com/user/repo.git --config " memory: 2GB cpu: 2 cores timeout: 30 minutes "
# List active containers /vm-list # Connect to specific container /vm-connect container-123 # Monitor container status /vm-status container-123
# Run development task in VM /agent vm-agent "Analyze this codebase and implement user authentication with proper tests" # Create feature in isolated environment /agent vm-agent "Add search functionality to the application with proper error handling"
Pull Request Automation
# Create pull request from VM container /vm-create-pr container-123 "Add user authentication" " Implemented complete user authentication system with: - JWT token-based authentication - Password hashing with bcrypt - Login/logout endpoints - Protected route middleware - Comprehensive tests "
Feature Development Workflow
# Complete feature development workflow /agent vm-agent " 1. Clone repository and analyze structure 2. Implement new feature: shopping cart functionality 3. Add comprehensive unit and integration tests 4. Update documentation 5. Create pull request with detailed description "
VM Agent Configuration Security Settings Permission Model
Resource Limits
# VM Agent operates with restricted permissions: File Access: - Read: ✅ /workspace/ * (container only ) - Write: ✅ /workspace/ * (container only ) - Delete: ❌ (container isolation ) Commands: - Allowed: git, npm, yarn, docker, code-server - Blocked: rm -rf, sudo, su, chmod 777 Network: - Allowed: github.com, npmjs.com, yarnpkg.com - API calls via secure proxy
# Default resource constraints: Container Limits: - Memory: 2GB default - CPU: 2 cores default - Disk: 10GB workspace - Network: Limited external access Execution: - Max concurrent tasks: 1 - Default timeout: 30 minutes - Token budget: 50,000 tokens - Retry attempts: 2
Configuration Options
# Configure VM container settings /vm-config --memory 4GB --cpu 4 --timeout 60 # Set environment variables /vm-config --env "NODE_ENV=development,DEBUG=true" # Configure networking /vm-config --network-isolation --allowed-domains "api.example.com"
# Setup development tools /vm-setup-dev --tools "node,python,git,docker" # Configure VS Code server /vm-vscode --extensions "ms-python.python,bradlc.vscode-tailwindcss" # Install project dependencies /vm-install-deps --auto-detect
Real-World Examples Full-Stack Feature Development # Complete feature development in isolated VM /agent vm-agent "Clone the e-commerce repository and implement the following: 1. Backend API endpoints for product reviews - POST /api/reviews (create review) - GET /api/products/:id/reviews (get product reviews) - PUT /api/reviews/:id (update review) - DELETE /api/reviews/:id (delete review) 2. Frontend React components - ReviewList component to display reviews - ReviewForm component for adding reviews - StarRating component for ratings - Integration with existing product pages 3. Database integration - Create reviews table with proper foreign keys - Add database migrations - Implement proper indexing for performance 4. Testing - Unit tests for API endpoints - React component tests with Testing Library - Integration tests for complete workflow 5. Documentation - Update API documentation - Add component documentation - Update README with new features 6. Create pull request with detailed description"
Legacy Code Modernization # Modernize legacy codebase in secure environment /agent vm-agent "Analyze this legacy Node.js application and modernize it: 1. Code Analysis - Identify outdated patterns and dependencies - Assess security vulnerabilities - Document current architecture 2. Modernization Steps - Update to latest Node.js LTS - Migrate to modern JavaScript (ES2022+) - Replace callbacks with async/await - Update dependencies to latest versions - Implement proper error handling 3. Add Missing Features - Proper logging with structured logs - Health check endpoints - Graceful shutdown handling - Configuration management with environment variables 4. Improve Code Quality - Add ESLint and Prettier configuration - Implement TypeScript for better type safety - Add comprehensive test coverage - Refactor large functions into smaller modules 5. Create comprehensive PR with migration guide"
Comparison with Universal Agent Feature Universal Agent VM Agent Execution Environment Host system Isolated container Security Model Configurable permissions Strict container isolation Capabilities 35 comprehensive 20 specialized for VMs Use Case General development tasks Secure/isolated development Repository Access Direct file system Container-based cloning Pull Request Creation Manual process Automated workflow Resource Isolation Host limitations Container boundaries API Communication Direct API calls Proxied through secure gateway
Best Practices When to Use VM Agent
Secure Development Use VM Agent for projects requiring strict isolation and security # Secure client project development /agent vm-agent "Work on sensitive client codebase with strict security requirements"
Repository Automation Perfect for automated repository analysis and PR creation # Automated repository improvements /agent vm-agent "Analyze repository for security issues and create fixes via PR"
Clean Environment Ideal for testing in clean, reproducible environments # Fresh environment testing /agent vm-agent "Test new feature in clean environment without affecting host"
Resource Isolation Use when you need guaranteed resource limits and isolation # Resource-controlled development /agent vm-agent "Develop memory-intensive feature with strict resource limits"
VM Agent Limitations
Performance Considerations
Cannot modify host system configuration
Limited network access to approved domains
No direct access to host file system
Restricted command execution capabilities
Maximum 50,000 token budget per session
Default 30-minute timeout for operations
Limited to single concurrent task
Container resource limits apply
Troubleshooting Common Issues
Container Creation Failed
Problem: VM container fails to startSolutions: # Check Docker daemon status /system-status --docker # Verify repository URL accessibility /test-connectivity https://github.com/user/repo.git # Check available resources /system-resources --available
Problem: Container connection times outSolutions: # Increase timeout /vm-config --timeout 60 # Check container status /vm-status container-id # Restart container if needed /vm-restart container-id
Problem: Container runs out of resourcesSolutions: # Increase container resources /vm-config --memory 4GB --cpu 4 # Monitor resource usage /vm-monitor container-id --resources # Clean up container /vm-cleanup container-id
Next Steps The VM Agent is ideal for secure, isolated development tasks where you need guaranteed resource limits and container-based execution. Use it for sensitive projects or when you need reproducible, clean development environments.
