build: integrate OpenSandbox as Agent Execution Sandbox

[chanzhi82020]

Summary

Integrate OpenSandbox as FastGPT's code execution sandbox solution, providing a more secure and scalable code execution environment. This PR includes complete Docker Compose and Kubernetes (Helm) deployment support.

Key Changes:

• ✨ Add OpenSandbox Helm Chart for Kubernetes deployment
• 🔧 Update all Docker Compose configurations to integrate opensandbox-server
• 📦 Upgrade fastgpt-sandbox to v4.14.7.2
• 🌍 Support both CN and global container registry configurations

What's Changed

1. OpenSandbox Helm Chart (deploy/helm/opensandbox/)

Complete Kubernetes deployment solution including:

• Core Components

  • Controller Manager: Manages BatchSandbox and Pool custom resources
  • Server: FastAPI control plane providing REST API
  • CRDs: BatchSandboxes and Pools custom resource definitions

• Configuration & Documentation

  • Comprehensive README and installation guide
  • Multiple deployment examples (kubectl-only, SDK-compatible, production, etc.)
  • Automated installation/uninstallation scripts
  • End-to-end test scripts

• Kubernetes Resources

  • RBAC configuration (ClusterRole, ServiceAccount, etc.)
  • Metrics support (ServiceMonitor)
  • High availability (Leader Election, PodDisruptionBudget)
  • Ingress support

2. Docker Compose Integration

Updated deployment configurations for all database variants:

• New Service: opensandbox-server

  • Port: 8090
  • Mounts Docker socket for container management
  • Configuration: TOML format with runtime, egress, security policies

• Security Configuration

  • Drop dangerous capabilities
  • Enable no_new_privileges
  • Limit PIDs (512)

• Network Configuration

  • Bridge mode networking
  • Access host via host.docker.internal
  • FastGPT adds OPENSANDBOX_SERVER_URL environment variable

3. Image & Version Management (deploy/args.json)

• New Images

  • opensandbox-server:v0.1.4
  • opensandbox-execd:v1.0.6
  • opensandbox-egress:v1.0.1

• Container Registries

  • CN: sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com
  • Global: opensandbox/*

• Version Upgrades

  • fastgpt-sandbox: v4.14.7.1 → v4.14.7.2

4. Affected Configuration Files

Development Environment

• deploy/dev/docker-compose.cn.yml
• deploy/dev/docker-compose.yml

Production Environment (All Database Variants)

• deploy/docker/{cn,global}/docker-compose.{pg,milvus,oceanbase,seekdb,zilliz}.yml
• deploy/templates/docker-compose.prod.yml

Documentation Site

• All configuration files under document/public/deploy/docker/

Technical Details

OpenSandbox Architecture

FastGPT → opensandbox-server:8090 → Docker Runtime
                ↓
          opensandbox-execd (execution container)
                ↓
          opensandbox-egress (network proxy)

Configuration Example

[runtime]
type = "docker"
execd_image = "opensandbox/execd:v1.0.6"

[docker]
network_mode = "bridge"
host_ip = "host.docker.internal"
drop_capabilities = ["SYS_ADMIN", "NET_ADMIN", ...]
pids_limit = 512

Testing Checklist

• Docker Compose deployment test (PostgreSQL)
• Docker Compose deployment test (Milvus)
• Kubernetes Helm deployment test
• OpenSandbox code execution functionality test
• CN container registry availability test
• Global container registry availability test

Breaking Changes

⚠️ Manual Actions Required:

1. Docker socket access permission required (/var/run/docker.sock)
2. FastGPT needs new environment variable OPENSANDBOX_SERVER_URL
3. Kubernetes deployment requires CRDs installation

Migration Guide

For Existing Docker Compose Users

# 1. Update configuration files
git pull origin feat-add-opensandbox-deploy

# 2. Restart services
docker-compose down
docker-compose up -d

# 3. Verify opensandbox-server status
curl http://localhost:8090/health

For Kubernetes Users

# 1. Install Helm Chart
cd deploy/helm/opensandbox
./scripts/install.sh

# 2. Verify deployment
kubectl get pods -n opensandbox-system

Documentation

New documentation added:

• deploy/helm/opensandbox/README.md - Helm Chart usage guide
• deploy/helm/opensandbox/examples/README.md - Deployment examples
• deploy/helm/opensandbox/scripts/README.md - Scripts documentation

Related Links

• OpenSandbox GitHub: https://github.com/alibaba/OpenSandbox
• Helm Chart Version: 0.1.0
• App Version: 0.0.1

Checklist

• Code passed lint checks
• Updated related documentation
• Tested Docker Compose deployment
• Tested Kubernetes deployment
• Updated changelog

---

Statistics

• 64 files changed
• 6,704 insertions(+)
• 26 deletions(-)
• Complete Kubernetes Operator support added

Files Changed Summary

New Files (52 files)

• Helm chart structure (deploy/helm/opensandbox/)
  • Core templates: deployment, service, RBAC, CRDs
  • Examples: pool configurations, batch sandbox definitions
  • Scripts: install, uninstall, e2e testing
  • Documentation: README, examples, directory structure

Modified Files (12 files)

• deploy/args.json - Image registry and version configuration
• All Docker Compose files (CN & Global variants)
  • PostgreSQL, Milvus, OceanBase, SeekDB, Zilliz
• Development environment configurations
• Documentation site deployment files

Deployment Topology

Docker Compose Deployment

┌─────────────────────────────────────────────┐
│  Host Machine                               │
│  ┌────────────┐  ┌──────────────────────┐  │
│  │  FastGPT   │──│  opensandbox-server  │  │
│  │  :3000     │  │  :8090               │  │
│  └────────────┘  └──────────────────────┘  │
│        │                    │               │
│        │         ┌──────────┴──────────┐   │
│        │         │  Docker Socket      │   │
│        │         │  /var/run/docker... │   │
│        │         └─────────────────────┘   │
│        │                    │               │
│        ▼                    ▼               │
│  ┌────────────┐  ┌──────────────────────┐  │
│  │  sandbox   │  │  opensandbox-execd   │  │
│  │  (legacy)  │  │  (dynamic)           │  │
│  └────────────┘  └──────────────────────┘  │
└─────────────────────────────────────────────┘

Kubernetes Deployment

┌─────────────────────────────────────────────────┐
│  Kubernetes Cluster                             │
│  ┌──────────────────────────────────────────┐  │
│  │  opensandbox-system namespace            │  │
│  │  ┌────────────────────────────────────┐  │  │
│  │  │  Controller Manager                │  │  │
│  │  │  - Watches CRDs                    │  │  │
│  │  │  - Manages Pools & BatchSandboxes  │  │  │
│  │  └────────────────────────────────────┘  │  │
│  │  ┌────────────────────────────────────┐  │  │
│  │  │  Server (FastAPI)                  │  │  │
│  │  │  - REST API for SDK                │  │  │
│  │  │  - Ingress/Service                 │  │  │
│  │  └────────────────────────────────────┘  │  │
│  └──────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────┐  │
│  │  User namespace                          │  │
│  │  ┌────────────────────────────────────┐  │  │
│  │  │  Pool Resources (CRDs)             │  │  │
│  │  │  - Pre-warmed sandbox pools        │  │  │
│  │  └────────────────────────────────────┘  │  │
│  └──────────────────────────────────────────┘  │
└─────────────────────────────────────────────────┘

Environment Variables

FastGPT New Environment Variable

# OpenSandbox server URL
OPENSANDBOX_SERVER_URL=http://opensandbox-server:8090

OpenSandbox Server Configuration

Set via TOML config file (/etc/opensandbox/config.toml):

• SANDBOX_CONFIG_PATH=/etc/opensandbox/config.toml

Security Considerations

1. Docker Socket Access: The opensandbox-server requires Docker socket access to manage containers. Ensure proper security measures are in place.

2. Capability Dropping: The following capabilities are dropped for security:

   • AUDIT_WRITE, MKNOD, NET_ADMIN, NET_RAW
   • SYS_ADMIN, SYS_MODULE, SYS_PTRACE
   • SYS_TIME, SYS_TTY_CONFIG

3. Resource Limits:

   • PIDs limited to 512 per container
   • no_new_privileges enabled

4. Network Isolation:

   • Bridge mode networking for isolation
   • Egress proxy for controlled outbound access

Performance Impact

• Startup Time: OpenSandbox may have slightly longer initialization time compared to the legacy sandbox due to additional security checks
• Resource Overhead: Minimal overhead from the opensandbox-server process (~50MB memory)
• Execution Speed: Comparable to legacy sandbox for code execution

Rollback Plan

If issues occur, you can rollback by:

1. Docker Compose:

   # Revert to previous version
   git checkout main
   docker-compose down
   docker-compose up -d

2. Kubernetes:

   helm uninstall opensandbox-controller -n opensandbox-system
   kubectl delete namespace opensandbox-system

Future Improvements

• Add Prometheus metrics dashboard templates
• Implement auto-scaling for Pool resources
• Add support for GPU-enabled sandboxes
• Enhance observability with distributed tracing
• Add webhook validation for CRDs

[github-actions]

Preview sandbox Image:

registry.cn-hangzhou.aliyuncs.com/fastgpt/fastgpt-pr:fastgpt_sandbox_04bf2d9bcf0a8bc824dbefdc63b1a9a0aae356fe

[github-actions]

Preview mcp_server Image:

registry.cn-hangzhou.aliyuncs.com/fastgpt/fastgpt-pr:fastgpt_mcp_server_04bf2d9bcf0a8bc824dbefdc63b1a9a0aae356fe

[github-actions]

Docs Preview:

---

🚀 FastGPT Document Preview Ready!

🔗 👀 Click here to visit preview

[github-actions]

Preview fastgpt Image:

registry.cn-hangzhou.aliyuncs.com/fastgpt/fastgpt-pr:fastgpt_04bf2d9bcf0a8bc824dbefdc63b1a9a0aae356fe

[chanzhi82020]

the latest opensandbox has support all-in-one helm chart, the docke-compose also support custom the container-networker-namespace

[github-actions]

Docs Preview Deployment Failed

Failed to deploy docs preview. Please check workflow logs.