mosaic/stack
1
0
Fork 0
Code Issues 10 Pull Requests Actions Packages Projects Releases 2 Wiki Activity
Files
173b429c6205f86041b720a6a4441bc867ef6abc
stack/docs/scratchpads/orch-106-sandbox.md
Jason Woltje 12abdfe81d feat(#93): implement agent spawn via federation 
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>
2026-02-03 14:37:06 -06:00

3.8 KiB
Raw Blame History

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

  • Read issue requirements from M6-NEW-ISSUES-TEMPLATES.md
  • Review existing orchestrator structure
  • Verify dockerode is installed in package.json
  • Review existing agent spawner code
  • Create scratchpad
  • Write unit tests for DockerSandboxService (RED)
  • Implement DockerSandboxService (GREEN)
  • Refactor and optimize (REFACTOR)
  • Verify test coverage (100% statements, 100% functions, 100% lines, 70% branches)
  • Update orchestrator config with sandbox settings
  • Update spawner module to include DockerSandboxService
  • Update spawner index.ts to export DockerSandboxService and types
  • Update AgentSession type to include containerId field
  • Typecheck passes
  • Build successful
  • Create Gitea issue #241
  • 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: #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
Reference in New Issue View Git Blame Copy Permalink