12abdfe81d
Implements FED-010: Agent Spawn via Federation feature that enables spawning and managing Claude agents on remote federated Mosaic Stack instances via COMMAND message type. Features: - Federation agent command types (spawn, status, kill) - FederationAgentService for handling agent operations - Integration with orchestrator's agent spawner/lifecycle services - API endpoints for spawning, querying status, and killing agents - Full command routing through federation COMMAND infrastructure - Comprehensive test coverage (12/12 tests passing) Architecture: - Hub → Spoke: Spawn agents on remote instances - Command flow: FederationController → FederationAgentService → CommandService → Remote Orchestrator - Response handling: Remote orchestrator returns agent status/results - Security: Connection validation, signature verification Files created: - apps/api/src/federation/types/federation-agent.types.ts - apps/api/src/federation/federation-agent.service.ts - apps/api/src/federation/federation-agent.service.spec.ts Files modified: - apps/api/src/federation/command.service.ts (agent command routing) - apps/api/src/federation/federation.controller.ts (agent endpoints) - apps/api/src/federation/federation.module.ts (service registration) - apps/orchestrator/src/api/agents/agents.controller.ts (status endpoint) - apps/orchestrator/src/api/agents/agents.module.ts (lifecycle integration) Testing: - 12/12 tests passing for FederationAgentService - All command service tests passing - TypeScript compilation successful - Linting passed Refs #93 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
114 lines
3.8 KiB
Markdown
114 lines
3.8 KiB
Markdown
# Issue ORCH-106: Docker sandbox isolation
|
|
|
|
## Objective
|
|
|
|
Implement Docker container isolation for agents using dockerode to provide security isolation, resource limits, and proper cleanup.
|
|
|
|
## Approach
|
|
|
|
Following TDD principles:
|
|
|
|
1. Write tests for DockerSandboxService
|
|
2. Implement DockerSandboxService with dockerode
|
|
3. Add configuration support (DOCKER_SOCKET, SANDBOX_ENABLED)
|
|
4. Ensure proper cleanup on agent completion
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] `src/spawner/docker-sandbox.service.ts` implemented
|
|
- [ ] dockerode integration for container management
|
|
- [ ] Agent runs in isolated container
|
|
- [ ] Resource limits enforced (CPU, memory)
|
|
- [ ] Non-root user in container
|
|
- [ ] Container cleanup on agent termination
|
|
- [ ] Comprehensive unit tests
|
|
- [ ] Test coverage >= 85%
|
|
|
|
## Progress
|
|
|
|
- [x] Read issue requirements from M6-NEW-ISSUES-TEMPLATES.md
|
|
- [x] Review existing orchestrator structure
|
|
- [x] Verify dockerode is installed in package.json
|
|
- [x] Review existing agent spawner code
|
|
- [x] Create scratchpad
|
|
- [x] Write unit tests for DockerSandboxService (RED)
|
|
- [x] Implement DockerSandboxService (GREEN)
|
|
- [x] Refactor and optimize (REFACTOR)
|
|
- [x] Verify test coverage (100% statements, 100% functions, 100% lines, 70% branches)
|
|
- [x] Update orchestrator config with sandbox settings
|
|
- [x] Update spawner module to include DockerSandboxService
|
|
- [x] Update spawner index.ts to export DockerSandboxService and types
|
|
- [x] Update AgentSession type to include containerId field
|
|
- [x] Typecheck passes
|
|
- [x] Build successful
|
|
- [x] Create Gitea issue #241
|
|
- [x] Close Gitea issue with completion notes
|
|
|
|
## Completion
|
|
|
|
ORCH-106 implementation completed successfully on 2026-02-02.
|
|
|
|
All acceptance criteria met:
|
|
|
|
- DockerSandboxService fully implemented with comprehensive test coverage
|
|
- Security features: non-root user, resource limits, network isolation
|
|
- Configuration-driven with environment variables
|
|
- Integrated into orchestrator spawner module
|
|
- Ready for use with AgentSpawnerService
|
|
|
|
Issue: https://git.mosaicstack.dev/mosaic/stack/issues/241
|
|
|
|
## Technical Notes
|
|
|
|
### Key Components
|
|
|
|
1. **DockerSandboxService**: Main service for container management
|
|
2. **Configuration**: Load from orchestrator.config.ts
|
|
3. **Resource Limits**: CPU and memory constraints
|
|
4. **Security**: Non-root user, network isolation options
|
|
5. **Cleanup**: Proper container removal on termination
|
|
|
|
### Docker Container Spec
|
|
|
|
- Base image: node:20-alpine
|
|
- Non-root user: nodejs:nodejs
|
|
- Resource limits:
|
|
- Memory: 512MB default (configurable)
|
|
- CPU: 1.0 default (configurable)
|
|
- Network: bridge (default), none (isolation mode)
|
|
- Volume mounts: workspace for git operations
|
|
- Auto-remove: false (manual cleanup for audit)
|
|
|
|
### Integration with AgentSpawnerService
|
|
|
|
- Check if sandbox mode enabled via options.sandbox
|
|
- If enabled, create Docker container via DockerSandboxService
|
|
- Mount workspace volume for git operations
|
|
- Pass containerId to agent session
|
|
- Cleanup container on agent completion/failure/kill
|
|
|
|
## Testing Strategy
|
|
|
|
1. Unit tests for DockerSandboxService:
|
|
- createContainer() - success and failure cases
|
|
- startContainer() - success and failure cases
|
|
- stopContainer() - success and failure cases
|
|
- removeContainer() - success and failure cases
|
|
- Resource limits applied correctly
|
|
- Non-root user configuration
|
|
- Network isolation options
|
|
2. Mock dockerode to avoid requiring actual Docker daemon
|
|
3. Test error handling for Docker failures
|
|
|
|
## Dependencies
|
|
|
|
- dockerode (already installed)
|
|
- @types/dockerode (already installed)
|
|
- ConfigService from @nestjs/config
|
|
|
|
## Related Files
|
|
|
|
- `/home/localadmin/src/mosaic-stack/apps/orchestrator/src/spawner/agent-spawner.service.ts`
|
|
- `/home/localadmin/src/mosaic-stack/apps/orchestrator/src/config/orchestrator.config.ts`
|
|
- `/home/localadmin/src/mosaic-stack/apps/orchestrator/src/spawner/types/agent-spawner.types.ts`
|