A secure command execution framework designed for AI/LLM agents to safely interact with system operations.
CI Status Release Status Go Report Card codecov
-
AI/LLM Integration
- AI-friendly command interface
- Secure execution environment
- Perfect for LLM tool chains
- Comprehensive audit logging
-
Execution Modes
- Local command execution
- Docker container isolation
- Interactive shell
- HTTP API service
-
Security Features
- Command execution auditing
- User permission control
- Resource usage monitoring
- Timeout control
-
Additional Features
- Environment variable management
- Working directory control
- I/O stream handling
- Error management
# Clone repository git clone https://github.com/iamlongalong/runshell.git cd runshell # Install dependencies make deps # Build project make build-local
# Build and run Docker container
make docker-build docker-run# Execute simple command runshell exec -- ls -l # Set working directory runshell exec --workdir /tmp -- ls -l # Set environment variables runshell exec --env KEY=VALUE env # Example of using Docker image runshell exec --docker-image ubuntu:latest -- ls -l runshell exec --docker-image busybox:latest --env KEY=VALUE env runshell exec --docker-image busybox:latest --workdir /app -- python3 script.py # Start HTTP server runshell server --http :8080
# Health check curl http://localhost:8080/api/v1/health # Execute command curl -X POST http://localhost:8080/api/v1/exec \ -H "Content-Type: application/json" \ -d '{ "command": "ls", "args": ["-l"], "workdir": "/tmp", "env": {"KEY": "VALUE"} }' # List available commands curl http://localhost:8080/api/v1/commands # Get command help curl http://localhost:8080/api/v1/help?command=ls # Session Management # Create new session, info: now does not support docker_config, only support options curl -X POST http://localhost:8080/api/v1/sessions \ -H "Content-Type: application/json" \ -d '{ "executor_type": "docker", "docker_config": { "image": "golang:1.20", "workdir": "/workspace", "bind_mount": "/local/path:/workspace" }, "options": { "workdir": "/workspace", "env": {"GOPROXY": "https://goproxy.cn,direct"} } }' # List all sessions curl http://localhost:8080/api/v1/sessions # Execute command in session curl -X POST http://localhost:8080/api/v1/sessions/{session_id}/exec \ -H "Content-Type: application/json" \ -d '{ "command": "ls", "args": ["-al"], "options": { "workdir": "/" } }' # Delete session curl -X DELETE http://localhost:8080/api/v1/sessions/{session_id} # Interactive shell (WebSocket) # npm install -g wscat wscat -c ws://localhost:8080/api/v1/exec/interactive # after connected, you can use the following commands: # ls -al # exit
The project provides a series of Make commands to simplify development and deployment:
make- Run default operations (clean, test, build)make clean- Clean build artifactsmake deps- Update dependenciesmake help- Show all available commands
make test- Run all testsmake test-unit- Run unit tests onlymake coverage- Generate coverage report
make build- Build for all platformsmake build-local- Build for current platform only
make docker-build- Build Docker imagemake docker-run- Run Docker containermake docker-stop- Stop Docker container
make fmt- Format codemake lint- Check code stylemake run- Run local servermake tag- Create new Git tag
-
Create Release Candidate:
# Create RC tag git tag -a v1.0.0-rc.1 -m "Release candidate 1 for version 1.0.0" git push origin v1.0.0-rc.1
-
Test Release Candidate:
- GitHub Actions will automatically:
- Create pre-release GitHub Release
- Build and upload binaries
- Build and push Docker RC image (
:rctag)
- Download and test pre-release version
- If issues found, fix and repeat steps 1-2, incrementing RC version
- GitHub Actions will automatically:
-
Create Official Release:
# Create release tag git tag -a v1.0.0 -m "Release version 1.0.0" git push origin v1.0.0
Docker images are available on Docker Hub:
# Use latest stable version docker pull iamlongalong/runshell:latest # Use pre-release version docker pull iamlongalong/runshell:rc # Use specific version docker pull iamlongalong/runshell:v1.0.0
- Fork the project
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Create a Pull Request
Before submitting code, please ensure:
- All tests pass (
make test) - Code meets standards (
make lint) - Documentation is updated
- Test cases are added
This project is licensed under the MIT License - see the LICENSE file for details.
- iamlongalong
Thanks to the following open source projects: