VM Agent

Secure virtualized development agent for isolated coding environments

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 management
• container-orchestration - Multi-container coordination
• isolated-execution - Secure sandboxed code execution
• repository-cloning - Automated Git repository setup
• vscode-server - Remote VS Code server integration
• autonomous-development - Self-directed development workflows
• pull-request-automation - Automated PR creation and management

Repository Management (5)

• repository-analysis - Deep codebase analysis and structure detection
• dependency-management - NPM/Yarn/PNPM package management
• testing-automation - Automated test execution and reporting
• documentation-generation - Auto-generated code documentation
• code-quality-analysis - Static analysis and quality metrics

Security Features (5)

• secure-api-communication - API key proxy with zero secret exposure
• token-budget-management - 50,000 token budget enforcement per session
• audit-logging - Complete activity audit trail
• resource-isolation - Container CPU/memory/disk limits
• credential-management - Secure JWT-based session management

Development Workflows (3)

• full-stack-development - Complete application development in containers
• ci-cd-integration - GitHub Actions/GitLab CI integration
• git-operations - Full Git workflow automation
• package-management - Dependency installation and updates
• environment-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

# 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
"

Pull Request Automation

Automated PR Creation

# 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

# 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

Configuration Options

Container Configuration

# 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"

Development Environment

# 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

• Container overhead may impact performance
• Network latency for external API calls
• Limited to container resources
• Slower file system operations compared to host

Feature Limitations

• Cannot modify host system configuration
• Limited network access to approved domains
• No direct access to host file system
• Restricted command execution capabilities

Resource Constraints

• 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 start

Solutions:

# 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

Connection Timeout

Problem: Container connection times out

Solutions:

# Increase timeout
/vm-config --timeout 60

# Check container status
/vm-status container-id

# Restart container if needed
/vm-restart container-id

Resource Exceeded

Problem: Container runs out of resources

Solutions:

# 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

Universal Agent

Learn about the comprehensive Universal Agent

Agent Architecture

Understand the agent system architecture

Advanced Examples

See advanced VM Agent development examples

Security Guide

Learn about VM security best practices

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.