{"id":22979880,"url":"https://github.com/iamlongalong/runshell","last_synced_at":"2025-04-02T09:21:36.056Z","repository":{"id":267159169,"uuid":"900415149","full_name":"iamlongalong/runshell","owner":"iamlongalong","description":"🤖 RunShell - A secure command execution framework designed for AI/LLM agents to safely interact with system operations.","archived":false,"fork":false,"pushed_at":"2024-12-18T16:09:31.000Z","size":273,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-08T00:28:22.614Z","etag":null,"topics":["agent-toolkit","ai-agents","command-executor","llm-tools","shell-wrappers","system-automation"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/iamlongalong.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-08T18:04:50.000Z","updated_at":"2024-12-18T15:55:21.000Z","dependencies_parsed_at":null,"dependency_job_id":"d91212e1-2586-43fc-bcfe-1eb05658ebf5","html_url":"https://github.com/iamlongalong/runshell","commit_stats":null,"previous_names":["iamlongalong/runshell"],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamlongalong%2Frunshell","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamlongalong%2Frunshell/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamlongalong%2Frunshell/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamlongalong%2Frunshell/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iamlongalong","download_url":"https://codeload.github.com/iamlongalong/runshell/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246785460,"owners_count":20833500,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-toolkit","ai-agents","command-executor","llm-tools","shell-wrappers","system-automation"],"created_at":"2024-12-15T01:34:53.486Z","updated_at":"2025-04-02T09:21:36.036Z","avatar_url":"https://github.com/iamlongalong.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# RunShell\n\nA secure command execution framework designed for AI/LLM agents to safely interact with system operations.\n\n[![English](https://img.shields.io/badge/README-English-blue)](README.md) [![中文](https://img.shields.io/badge/README-中文-red)](README_zh.md)\n\n![CI Status](https://github.com/iamlongalong/runshell/workflows/CI/badge.svg)\n![Release Status](https://github.com/iamlongalong/runshell/workflows/Release/badge.svg)\n[![Go Report Card](https://goreportcard.com/badge/github.com/iamlongalong/runshell)](https://goreportcard.com/report/github.com/iamlongalong/runshell)\n[![codecov](https://codecov.io/gh/iamlongalong/runshell/branch/main/graph/badge.svg)](https://codecov.io/gh/iamlongalong/runshell)\n\n## Features\n\n- **AI/LLM Integration**\n  - AI-friendly command interface\n  - Secure execution environment\n  - Perfect for LLM tool chains\n  - Comprehensive audit logging\n\n- **Execution Modes**\n  - Local command execution\n  - Docker container isolation\n  - Interactive shell\n  - HTTP API service\n\n- **Security Features**\n  - Command execution auditing\n  - User permission control\n  - Resource usage monitoring\n  - Timeout control\n\n- **Additional Features**\n  - Environment variable management\n  - Working directory control\n  - I/O stream handling\n  - Error management\n\n## Quick Start\n\n### Installation\n\n#### From Source\n\n```bash\n# Clone repository\ngit clone https://github.com/iamlongalong/runshell.git\ncd runshell\n\n# Install dependencies\nmake deps\n\n# Build project\nmake build-local\n```\n\n#### Using Docker\n\n```bash\n# Build and run Docker container\nmake docker-build docker-run\n```\n\n### Usage\n\n#### Command Line\n\n```bash\n# Execute simple command\nrunshell exec -- ls -l\n\n# Set working directory\nrunshell exec --workdir /tmp -- ls -l\n\n# Set environment variables\nrunshell exec --env KEY=VALUE env\n\n# Example of using Docker image\nrunshell exec --docker-image ubuntu:latest -- ls -l\nrunshell exec --docker-image busybox:latest --env KEY=VALUE env\nrunshell exec --docker-image busybox:latest --workdir /app -- python3 script.py\n\n# Start HTTP server\nrunshell server --http :8080\n```\n\n#### HTTP API Examples\n\n```bash\n# Health check\ncurl http://localhost:8080/api/v1/health\n\n# Execute command\ncurl -X POST http://localhost:8080/api/v1/exec \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"command\": \"ls\",\n    \"args\": [\"-l\"],\n    \"workdir\": \"/tmp\",\n    \"env\": {\"KEY\": \"VALUE\"}\n  }'\n\n# List available commands\ncurl http://localhost:8080/api/v1/commands\n\n# Get command help\ncurl http://localhost:8080/api/v1/help?command=ls\n\n# Session Management\n# Create new session, info: now does not support docker_config, only support options\ncurl -X POST http://localhost:8080/api/v1/sessions \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"executor_type\": \"docker\",\n    \"docker_config\": {\n      \"image\": \"golang:1.20\",\n      \"workdir\": \"/workspace\",\n      \"bind_mount\": \"/local/path:/workspace\"\n    },\n    \"options\": {\n      \"workdir\": \"/workspace\",\n      \"env\": {\"GOPROXY\": \"https://goproxy.cn,direct\"}\n    }\n  }'\n\n# List all sessions\ncurl http://localhost:8080/api/v1/sessions\n\n# Execute command in session\ncurl -X POST http://localhost:8080/api/v1/sessions/{session_id}/exec \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"command\": \"ls\",\n    \"args\": [\"-al\"],\n    \"options\": {\n      \"workdir\": \"/\"\n    }\n  }'\n\n# Delete session\ncurl -X DELETE http://localhost:8080/api/v1/sessions/{session_id}\n\n# Interactive shell (WebSocket)\n# npm install -g wscat\nwscat -c ws://localhost:8080/api/v1/exec/interactive\n# after connected, you can use the following commands:\n# ls -al\n# exit\n```\n\n## Development Guide\n\n### Make Commands\n\nThe project provides a series of Make commands to simplify development and deployment:\n\n#### Basic Operations\n- `make` - Run default operations (clean, test, build)\n- `make clean` - Clean build artifacts\n- `make deps` - Update dependencies\n- `make help` - Show all available commands\n\n#### Testing\n- `make test` - Run all tests\n- `make test-unit` - Run unit tests only\n- `make coverage` - Generate coverage report\n\n#### Building\n- `make build` - Build for all platforms\n- `make build-local` - Build for current platform only\n\n#### Docker Operations\n- `make docker-build` - Build Docker image\n- `make docker-run` - Run Docker container\n- `make docker-stop` - Stop Docker container\n\n#### Development Tools\n- `make fmt` - Format code\n- `make lint` - Check code style\n- `make run` - Run local server\n- `make tag` - Create new Git tag\n\n### Release Process\n\n1. Create Release Candidate:\n   ```bash\n   # Create RC tag\n   git tag -a v1.0.0-rc.1 -m \"Release candidate 1 for version 1.0.0\"\n   git push origin v1.0.0-rc.1\n   ```\n\n2. Test Release Candidate:\n   - GitHub Actions will automatically:\n     - Create pre-release GitHub Release\n     - Build and upload binaries\n     - Build and push Docker RC image (`:rc` tag)\n   - Download and test pre-release version\n   - If issues found, fix and repeat steps 1-2, incrementing RC version\n\n3. Create Official Release:\n   ```bash\n   # Create release tag\n   git tag -a v1.0.0 -m \"Release version 1.0.0\"\n   git push origin v1.0.0\n   ```\n\n### Docker Images\n\nDocker images are available on Docker Hub:\n\n```bash\n# Use latest stable version\ndocker pull iamlongalong/runshell:latest\n\n# Use pre-release version\ndocker pull iamlongalong/runshell:rc\n\n# Use specific version\ndocker pull iamlongalong/runshell:v1.0.0\n```\n\n## Contributing\n\n1. Fork the project\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Create a Pull Request\n\nBefore submitting code, please ensure:\n\n1. All tests pass (`make test`)\n2. Code meets standards (`make lint`)\n3. Documentation is updated\n4. Test cases are added\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Author\n\n- iamlongalong\n\n## Acknowledgments\n\nThanks to the following open source projects:\n\n- [cobra](https://github.com/spf13/cobra)\n- [docker](https://github.com/docker/docker) ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiamlongalong%2Frunshell","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fiamlongalong%2Frunshell","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiamlongalong%2Frunshell/lists"}