Joysafeter
please add desp
Installation
npx joysafeterAsk AI about Joysafeter
Powered by Claude ยท Grounded in docs
I know everything about Joysafeter. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation

JoySafeter
The AI-native platform for building, orchestrating, and running security agents at scale.
From idea to production-grade security automation โ in minutes, not months.
English | ็ฎไฝไธญๆ
Why JoySafeter
Traditional security tooling hits a ceiling: scripts are brittle, single agents lack context, and complex scenarios require 2โ3 engineers working in parallel. JoySafeter breaks that ceiling.
| Challenge | Traditional Approach | JoySafeter |
|---|---|---|
| APK vulnerability analysis | Manual MobSF + engineer review | Autonomous agent: upload โ analyze โ report |
| Penetration testing | Fixed scripts, static playbooks | Dynamic DeepAgents that adapt to findings in real time |
| Tool integration | Custom glue code per tool | 200+ tools via MCP Protocol, zero glue |
| Scale | Linear headcount growth | Agent teams that multiply capacity |
JoySafeter defines a new paradigm: AI-driven Security Operations (AISecOps) โ where multi-agent collaboration, cognitive memory, and scenario-matched skills replace manual coordination.
Real-World Cases
Case 1 โ APK Vulnerability Detection Agent
Upload an APK. Get an OWASP Mobile Top 10 report. No engineer required.
How it works:
- User uploads the APK file
- Agent invokes MobSF for static analysis
- Extracts critical risk signals โ permission abuse, hardcoded secrets, insecure network config
- Deep-validates high-severity findings via Frida dynamic instrumentation
- Auto-generates a structured report aligned to OWASP Mobile Top 10
The entire flow โ from upload to report โ requires zero manual intervention, covering work that traditionally takes 2โ3 security engineers.
Case 2 โ Penetration Testing Agent
Describe the target and scope. The agent plans, executes, and adapts โ then delivers a report.
How it works:
- Open the Workbench and create a new agent
- Enable DeepAgents mode โ select penetration testing skills
- Provide an authorized target URL and test requirements
- Agent runs autonomously โ if it discovers a login page, it automatically triggers auth bypass testing
- Download the final report when the run completes
Note: Requires sandbox image
swr.cn-north-4.myhuaweicloud.com/ddn-k8s/ghcr.io/jd-opensource/joysafeter-sandbox:latestconfigured in Sandbox Settings.
This dynamic decision-making โ where the agent adapts its next step based on what it finds โ is what fixed scripts cannot replicate.
Core Capabilities
Visual Agent Builder
|
200+ Security Tools, Ready to Use
|
DeepAgents Orchestration
|
Enterprise Ready
|
Quick Start
One-Click Launch (Recommended)
./deploy/quick-start.sh
The script provides an interactive menu to choose your startup mode and customize ports (with conflict detection):
| Mode | Description | Ports Configured |
|---|---|---|
| (1) Docker Compose Full Stack | All services in containers, supports localhost or remote server IP/domain | Frontend, Backend, PostgreSQL, Redis |
| (2) Local Frontend Only | bun run dev, supports connecting to remote backend | Frontend (can specify remote backend address) |
| (3) Local Backend Only | uvicorn --reload, supports remote DB/Redis | Backend (can specify remote DB/Redis/frontend address) |
| (4) Local Frontend + Backend | Auto-starts middleware, supports exposing via non-localhost address | Frontend, Backend |
All modes support remote deployment scenarios:
- Docker Compose Full Stack โ choose deployment address (localhost or IP/domain) + http/https
- Local Frontend Only โ optionally connect to a remote backend API (enter backend IP + port + protocol)
- Local Backend Only โ optionally connect to remote PostgreSQL, Redis, and frontend (enter each address and port)
- Local Frontend + Backend โ optionally expose services via a non-localhost address
- Non-localhost deployments automatically update
frontend/.envCSP whitelist (NEXT_PUBLIC_CSP_CONNECT_SRC_EXTRA)
./deploy/quick-start.sh --skip-env # Skip .env file initialization
./deploy/quick-start.sh --skip-db-init # Skip database initialization
Launch by Scenario
# โโโ Development โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
./deploy/scripts/dev.sh # Docker full-stack dev (containerized frontend + backend)
./deploy/scripts/dev-local.sh # Local dev prep (start middleware, run backend/frontend on host)
./deploy/scripts/dev-backend.sh # Local backend only (requires middleware running)
./deploy/scripts/dev-frontend.sh # Local frontend only (requires backend running)
# โโโ Production โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
./deploy/scripts/prod.sh # Production deploy (pre-built images + docker-compose.prod.yml)
./deploy/scripts/prod.sh --skip-mcp # Production without MCP service
./deploy/scripts/prod.sh --skip-pull # Skip image pull, use local images
# โโโ Middleware / Infrastructure โโโโโโโโโโโโโโโโโโโโโโโโ
./deploy/scripts/start-middleware.sh # Start middleware (PostgreSQL + Redis + MCP)
./deploy/scripts/minimal.sh # Minimal startup (PostgreSQL + Redis only)
./deploy/scripts/minimal.sh --with-mcp # Minimal + MCP service
./deploy/scripts/stop-middleware.sh # Stop middleware
# โโโ Test / CI โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
./deploy/scripts/test.sh # Test environment (minimal deps, automation-friendly)
# โโโ Install / Check โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
./deploy/install.sh # Interactive installation wizard (generates config files)
./deploy/install.sh --mode dev --non-interactive # Non-interactive install
./deploy/scripts/check-env.sh # Environment preflight (Docker, ports, config files)
# โโโ Image Management โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
./deploy/deploy.sh build # Build frontend + backend images
./deploy/deploy.sh build --all # Build all images (including OpenClaw)
./deploy/deploy.sh push # Build and push to registry
./deploy/deploy.sh pull # Pull latest pre-built images
Default Ports
| Service | Port | URL |
|---|---|---|
| Frontend | 3000 | http://localhost:3000 |
| Backend API | 8000 | http://localhost:8000 |
| API Docs | 8000/docs | Swagger UI |
| PostgreSQL | 5432 | Database |
| Redis | 6379 | Cache |
Prerequisites: Docker + Docker Compose. See INSTALL.md for detailed installation guide, deploy/PRODUCTION_IP_GUIDE.md for production deployment.
Architecture
Full architecture details: docs/ARCHITECTURE.md
Key design principles:
- Graph-based execution โ every agent workflow is a stateful LangGraph, enabling pause, resume, and branch
- Unified Run Center โ Chat, Copilot, and Skill Creator share a single event-sourced run lifecycle (Run โ Event โ Snapshot)
- Unified WebSocket layer โ BaseWsClient abstract class; Chat / Run / Notification clients share lifecycle, auth (ws-token), and reconnect logic
- Full-chain trace_id propagation โ contextvars-based request tracing from HTTP/WS entry through LangGraph to persistence
- Glass-box observability โ real-time Langfuse tracing of every agent decision and state transition
- RAII sandbox isolation โ per-user Docker containers with automatic handle release, zero state leakage
- Canonical model identifiers โ full-stack (provider_name, model_name) resolution via ModelService โ ModelFactory
- Layered skill system โ skills are versioned units that compose into workflows without coupling
User Journey โ Quick Start in 9 Steps
Login โ Configure Models โ MCP Tools โ Skill Management โ Build Agent โ Self-Test (Langfuse Trace) โ Publish โ Chat UI โ Run Center
Tech Stack
| Layer | Technology | Purpose |
|---|---|---|
| Frontend | Next.js 16, React 19, TypeScript | Server-side rendering, App Router |
| UI | Radix UI, Tailwind CSS, Framer Motion | Accessible, animated components |
| State | Zustand, TanStack Query | Client & server state |
| Workflow Editor | React Flow | Interactive node-based builder |
| Backend | FastAPI, Python 3.12+ | Async API with OpenAPI docs |
| AI Framework | LangChain, LangGraph, DeepAgents | Agent orchestration & workflows |
| MCP | mcp 1.20+, fastmcp 2.14+ | Tool protocol support |
| Database | PostgreSQL, SQLAlchemy 2.0 | Async ORM with migrations |
| Cache | Redis | Session cache & rate limiting |
| Observability | Langfuse, Loguru | Tracing & structured logging |
What's New
Full history: CHANGELOG.md
| Tag | Feature | What it means |
|---|---|---|
| NEW | Run Center Architecture | Chat & Copilot fully integrated into Run Center โ run details, session recovery, and live event replay on page refresh |
| NEW | Dark Mode & Preferences | System / Light / Dark theme switching; redesigned profile page with language & theme preferences |
| NEW | Unified WebSocket Layer | BaseWsClient abstract class โ Chat, Run, and Notification clients share lifecycle, auth (ws-token), and reconnect logic |
| NEW | Full-Chain trace_id Propagation | End-to-end request tracing via contextvars for complete observability |
| NEW | Ollama One-Click Integration | Local Ollama model provider added out of the box |
| NEW | Version Display | In-app version info tied to bump-version.sh release pipeline |
| NEW | Unified Model Identifiers | Full-stack (provider_name, model_name) canonical form with data migration โ no more legacy field ambiguity |
| UPGRADE | Design Token Overhaul | Hardcoded colors, font sizes, and border radii replaced with CSS variables and Tailwind tokens; z-index and typography scales unified |
| UPGRADE | Sandbox Overhaul | RAII handle management, adapter API uploads, security hardening |
| UPGRADE | Frontend Component Extraction | ConfirmDialog, UnifiedDialog, InlineRenameInput, SidebarContextMenu, AgentListContext โ less prop drilling, more reuse |
| UPGRADE | i18n & Code Quality | Backend error messages internationalized; email templates moved to Jinja2; LLM prompts externalized to Markdown; 129 unused SVG icons removed |
Documentation
Getting Started
- INSTALL.md โ Installation guide (Docker / manual / pre-built images)
- DEVELOPMENT.md โ Local development setup
- deploy/README.md โ Docker deployment
- deploy/PRODUCTION_IP_GUIDE.md โ Production deployment
Deep Dive
- docs/ARCHITECTURE.md โ Architecture overview
- backend/README.md โ Backend guide
- frontend/README.md โ Frontend guide
Tutorials
See docs/tutorials/ for step-by-step guides on model setup, MCP integration, skill development, and more.
Governance
- CONTRIBUTING.md โ Contributing guide
- SECURITY.md โ Security policy
- CODE_OF_CONDUCT.md โ Code of conduct
Community
Join the WeChat user group for questions and discussion:
ย ย ย ย
Contributing
git clone https://github.com/jd-opensource/JoySafeter.git
git checkout -b feature/amazing-feature
git commit -m 'feat: add amazing feature'
git push origin feature/amazing-feature
See CONTRIBUTING.md for full guidelines.
License
Apache License 2.0 โ see LICENSE for details.
Third-party component licenses: THIRD_PARTY_LICENSES.md
Acknowledgments
LangChain | LangGraph | FastAPI | Next.js | Radix UI |
Made with โค๏ธ by the JoySafeter Team
For commercial solutions, contact JD Technology Solutions Team at org.ospo1@jd.com
