A distributed task execution platform that provides secure, scalable code execution in containerized environments with comprehensive task management capabilities.
VoidRunner is designed to safely execute user-submitted code in isolated containers while providing a robust API for task management, real-time monitoring, and execution tracking. The platform prioritizes security, scalability, and developer experience.
Authentication & Security
- JWT-based user authentication with access and refresh tokens
- Input validation, rate limiting, and secure request handling
- Docker container isolation with seccomp profiles and resource limits
Task Management
- Full CRUD operations for code tasks with metadata support
- Asynchronous task execution with real-time status tracking
- Task prioritization and retry logic with dead letter handling
Execution Engine
- Secure Docker-based code execution in isolated containers
- Embedded worker pool with concurrency controls and health monitoring
- Redis-based task queuing with automatic cleanup
Monitoring & API
- RESTful API with 16+ endpoints for complete task lifecycle management
- Real-time health checks and worker status monitoring
- PostgreSQL integration with optimized schema and cursor pagination
Single-process architecture with embedded worker pool for development and production
┌─────────────────┐ ┌─────────────────────────────────┐ ┌─────────────────┐
│ Web Clients │ │ API Server │ │ Database │
│ (Postman/curl) │◄──►│ ┌─────────────────────────┐ │◄──►│ (PostgreSQL) │
│ │ │ │ HTTP API │ │ │ │
└─────────────────┘ │ │ - Authentication │ │ └─────────────────┘
│ │ - Task Management │ │
│ └─────────────────────────┘ │ ┌─────────────────┐
│ ┌─────────────────────────┐ │◄──►│ Message Queues │
│ │ Embedded Workers │ │ │ (Redis) │
│ │ - Task Processing │ │ │ │
│ │ - Docker Execution │ │ └─────────────────┘
│ │ - Health Monitoring │ │
│ │ - Concurrency Control │ │ ┌───────────────────┐
│ └─────────────────────────┘ │◄──►│ Container Runtime │
└─────────────────────────────────┘ │ (Docker) │
│ │
└───────────────────┘
- Docker & Docker Compose - For containerized execution and development environment
- Go 1.24.4+ - For local development and building from source
- Make - For standardized build and development commands
- PostgreSQL 15+ - For database operations (auto-configured in development)
- Redis 7+ - For task queuing (auto-configured in development)
The fastest way to get started with VoidRunner:
# 1. Clone and setup
git clone https://github.com/voidrunnerhq/voidrunner.git
cd voidrunner
make setup
# 2. Start development environment (includes DB, Redis, API with embedded workers)
make dev-up
# 3. Verify it's running
make dev-statusThis starts the complete environment on http://localhost:8080
Once running, verify your setup:
Health Check Endpoints:
- API Health: http://localhost:8080/health
- Worker Status: http://localhost:8080/health/workers
- API Documentation: http://localhost:8080/docs
POST /api/v1/auth/register- Register new userPOST /api/v1/auth/login- User loginPOST /api/v1/auth/refresh- Refresh access tokenPOST /api/v1/auth/logout- User logoutGET /api/v1/auth/me- Get current user info
POST /api/v1/tasks- Create new taskGET /api/v1/tasks- List user's tasks (with pagination)GET /api/v1/tasks/{id}- Get task detailsPUT /api/v1/tasks/{id}- Update taskDELETE /api/v1/tasks/{id}- Delete task
POST /api/v1/tasks/{id}/executions- Start task executionGET /api/v1/tasks/{id}/executions- List task executionsGET /api/v1/executions/{id}- Get execution detailsPUT /api/v1/executions/{id}- Update execution statusDELETE /api/v1/executions/{id}- Cancel execution
GET /health- API health check endpointGET /health/workers- Embedded worker status and metricsGET /ready- Readiness check endpoint
To build from source or customize the setup:
# 1. Clone the repository
git clone https://github.com/voidrunnerhq/voidrunner.git
cd voidrunner
# 2. Setup development environment
make setup
# 3. Configure environment
cp .env.example .env
# Edit .env with your configuration
# 4. Start dependencies and run migrations
make services-start
make migrate-up
# 5. Start the server
make devmake test # Unit tests
make test-integration # Integration tests (requires PostgreSQL)For detailed testing instructions, see Testing Guide.
Interactive API documentation:
make docs-serve # Serve docs locally at http://localhost:8081The application uses environment variables for configuration. Copy .env.example to .env and adjust values as needed:
- Server: HOST, PORT, ENV settings
- Database: Connection details for PostgreSQL
- Redis: Queue system connection details (required for task processing)
- JWT: Token configuration and secrets
- CORS: Frontend domain configuration
- Logging: Level and format settings
Note: Redis configuration is required for task queuing and execution. The .env.example file includes complete database, Redis, and JWT settings. For manual setup, use make services-start to start both PostgreSQL and Redis test services.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'feat: add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
Please ensure all tests pass and maintain code coverage above 80%.
This project is licensed under the MIT License - see the LICENSE file for details.