| Name | ssh-agent-bridge JSON |
| Version |
0.1.1
JSON |
| download |
| home_page | None |
| Summary | High-level SSH session management for AI agents |
| upload_time | 2025-10-26 15:16:11 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | MIT |
| keywords |
ssh
async
agent
ai
session
command
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# SSH Agent Bridge
[](https://pypi.org/project/ssh-agent-bridge/)
[](https://pypi.org/project/ssh-agent-bridge/)
[](https://opensource.org/licenses/MIT)
A Python package that provides high-level SSH session management for AI agents. Enables non-interactive agents to communicate with remote VMs over SSH using a tool-based interface with structured parameters and returns.
## Key Features
- **Agent-Centric Design**: Connection pooling per agent with session isolation
- **Structured Communication**: No CLI streaming - structured parameters and returns
- **Marker-Based Execution**: Reliable command completion detection with exit codes
- **Interactive Support**: Handle prompts, passwords, and confirmations
- **Signal Handling**: Send SIGINT, SIGKILL, and other signals to processes
- **Async First**: Built on asyncio for high concurrency and performance
- **Timeout Management**: Configurable timeouts with graceful degradation
## Installation
```bash
pip install ssh-agent-bridge
```
For development:
```bash
git clone https://github.com/Ganzzi/ssh_agent_bridge.git
cd ssh_agent_bridge
pip install -e .[dev]
```
## Quick Start
### Simple Ephemeral Command
```python
import asyncio
from ssh_agent_bridge import SSHService
async def main():
service = SSHService()
try:
result = await service.run_ephemeral(
agent_id="my-agent",
host="example.com",
command="echo 'Hello, World!'",
username="myuser",
password="mypassword"
)
print(f"Exit code: {result.exit_code}")
print(f"Output: {result.stdout}")
finally:
await service.shutdown()
asyncio.run(main())
```
### Persistent Session
```python
import asyncio
from ssh_agent_bridge import SSHService
async def main():
service = SSHService()
try:
# Create session
session_id = await service.create_session(
agent_id="my-agent",
host="example.com",
username="myuser",
password="mypassword"
)
# Run multiple commands
commands = ["pwd", "ls -la", "whoami"]
for cmd in commands:
result = await service.run_command(session_id, cmd)
print(f"$ {cmd}")
print(result.stdout)
# Clean up
await service.end_session(session_id)
finally:
await service.shutdown()
asyncio.run(main())
```
## Documentation
- **[API Reference](docs/API.md)** - Complete method signatures and parameters
- **[User Guide](docs/GUIDE.md)** - Installation, usage patterns, and best practices
- **[Architecture](docs/ARCHITECTURE.md)** - Design decisions and technical details
- **[Development Plan](docs/plan/DEVELOPMENT_PLAN.md)** - Project roadmap and implementation status
## Requirements
- Python 3.8+
- SSH server access (OpenSSH recommended)
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## Development
### Setup
```bash
# Install development dependencies
pip install -r requirements-dev.txt
# Run tests
pytest
# Run type checking
mypy src/
# Format code
black src/
```
### Testing
```bash
# Run all tests (55/55 core tests PASS - 100% pass rate)
uv run pytest tests/test_core.py -v
# Run with coverage (86% coverage, exceeds 80% target)
uv run pytest tests/test_core.py --cov=src/ssh_agent_bridge --cov-report=html
# Run core unit tests
uv run pytest tests/test_core.py::TestDataTypes tests/test_core.py::TestExceptions tests/test_core.py::TestSSHService tests/test_core.py::TestConnectionManagement tests/test_core.py::TestSessionLifecycle tests/test_core.py::TestCommandExecution -v
```
For detailed testing information, see:
- **[TEST_RUNNER_STRATEGY.md](tests/TEST_RUNNER_STRATEGY.md)** - Safe test execution guide
- **[TESTING_PATTERNS.md](tests/TESTING_PATTERNS.md)** - Patterns and anti-patterns
## Project Status
**Phase 6 Complete ✅ | Released on PyPI 🚀**
### Current Phase: Phase 6 - Packaging & Release (COMPLETE)
#### Phase 6 Completion
- ✅ **Build System:** PEP 517 build configured, wheel & sdist generation tested
- ✅ **PyPI Preparation:** Package metadata, classifiers, and documentation uploaded
- ✅ **Release Process:** Version 0.1.1 tagged and released to PyPI
- ✅ **Package Available:** https://pypi.org/project/ssh-agent-bridge/
#### Final Test Status
- ✅ **55/55 core tests PASS** (100% pass rate)
- ✅ **86% Code Coverage** (exceeded 80% target)
- ✅ **7/7 Example Scripts** (all working successfully)
- ✅ **100% Core Functionality** (production ready)
#### Next Phase: Phase 7 - Maintenance & Enhancements
- � **User Feedback:** Collect issues and feature requests
- 🔧 **Maintenance:** Bug fixes and security updates
- ✨ **Future Features:** Connection multiplexing, advanced prompt detection, SFTP support
- 🌐 **Community:** Documentation improvements, contribution guidelines
## Support
If you find this project helpful, please consider:
- ⭐ Starring the repository
- 🐛 Reporting bugs or issues
- 💡 Suggesting features or improvements
- 📖 Contributing documentation
## Related Projects
- [asyncssh](https://github.com/ronf/asyncssh) - Underlying SSH protocol implementation
- [paramiko](https://github.com/paramiko/paramiko) - Alternative SSH library for Python
Raw data
{
"_id": null,
"home_page": null,
"name": "ssh-agent-bridge",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "SSH Agent Bridge Team <team@example.com>",
"keywords": "ssh, async, agent, ai, session, command",
"author": null,
"author_email": "SSH Agent Bridge Team <team@example.com>",
"download_url": "https://files.pythonhosted.org/packages/4f/38/e22a8a85bdb0189f8950c1e900dff3cf85c6456ded838c6b4907ed1abc34/ssh_agent_bridge-0.1.1.tar.gz",
"platform": null,
"description": "# SSH Agent Bridge\r\n\r\n[](https://pypi.org/project/ssh-agent-bridge/)\r\n[](https://pypi.org/project/ssh-agent-bridge/)\r\n[](https://opensource.org/licenses/MIT)\r\n\r\nA Python package that provides high-level SSH session management for AI agents. Enables non-interactive agents to communicate with remote VMs over SSH using a tool-based interface with structured parameters and returns.\r\n\r\n## Key Features\r\n\r\n- **Agent-Centric Design**: Connection pooling per agent with session isolation\r\n- **Structured Communication**: No CLI streaming - structured parameters and returns\r\n- **Marker-Based Execution**: Reliable command completion detection with exit codes\r\n- **Interactive Support**: Handle prompts, passwords, and confirmations\r\n- **Signal Handling**: Send SIGINT, SIGKILL, and other signals to processes\r\n- **Async First**: Built on asyncio for high concurrency and performance\r\n- **Timeout Management**: Configurable timeouts with graceful degradation\r\n\r\n## Installation\r\n\r\n```bash\r\npip install ssh-agent-bridge\r\n```\r\n\r\nFor development:\r\n\r\n```bash\r\ngit clone https://github.com/Ganzzi/ssh_agent_bridge.git\r\ncd ssh_agent_bridge\r\npip install -e .[dev]\r\n```\r\n\r\n## Quick Start\r\n\r\n### Simple Ephemeral Command\r\n\r\n```python\r\nimport asyncio\r\nfrom ssh_agent_bridge import SSHService\r\n\r\nasync def main():\r\n service = SSHService()\r\n\r\n try:\r\n result = await service.run_ephemeral(\r\n agent_id=\"my-agent\",\r\n host=\"example.com\",\r\n command=\"echo 'Hello, World!'\",\r\n username=\"myuser\",\r\n password=\"mypassword\"\r\n )\r\n\r\n print(f\"Exit code: {result.exit_code}\")\r\n print(f\"Output: {result.stdout}\")\r\n\r\n finally:\r\n await service.shutdown()\r\n\r\nasyncio.run(main())\r\n```\r\n\r\n### Persistent Session\r\n\r\n```python\r\nimport asyncio\r\nfrom ssh_agent_bridge import SSHService\r\n\r\nasync def main():\r\n service = SSHService()\r\n\r\n try:\r\n # Create session\r\n session_id = await service.create_session(\r\n agent_id=\"my-agent\",\r\n host=\"example.com\",\r\n username=\"myuser\",\r\n password=\"mypassword\"\r\n )\r\n\r\n # Run multiple commands\r\n commands = [\"pwd\", \"ls -la\", \"whoami\"]\r\n for cmd in commands:\r\n result = await service.run_command(session_id, cmd)\r\n print(f\"$ {cmd}\")\r\n print(result.stdout)\r\n\r\n # Clean up\r\n await service.end_session(session_id)\r\n\r\n finally:\r\n await service.shutdown()\r\n\r\nasyncio.run(main())\r\n```\r\n\r\n## Documentation\r\n\r\n- **[API Reference](docs/API.md)** - Complete method signatures and parameters\r\n- **[User Guide](docs/GUIDE.md)** - Installation, usage patterns, and best practices\r\n- **[Architecture](docs/ARCHITECTURE.md)** - Design decisions and technical details\r\n- **[Development Plan](docs/plan/DEVELOPMENT_PLAN.md)** - Project roadmap and implementation status\r\n\r\n## Requirements\r\n\r\n- Python 3.8+\r\n- SSH server access (OpenSSH recommended)\r\n\r\n## License\r\n\r\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\r\n\r\n## Contributing\r\n\r\nContributions are welcome! Please feel free to submit a Pull Request.\r\n\r\n1. Fork the repository\r\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\r\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\r\n4. Push to the branch (`git push origin feature/amazing-feature`)\r\n5. Open a Pull Request\r\n\r\n## Development\r\n\r\n### Setup\r\n\r\n```bash\r\n# Install development dependencies\r\npip install -r requirements-dev.txt\r\n\r\n# Run tests\r\npytest\r\n\r\n# Run type checking\r\nmypy src/\r\n\r\n# Format code\r\nblack src/\r\n```\r\n\r\n### Testing\r\n\r\n```bash\r\n# Run all tests (55/55 core tests PASS - 100% pass rate)\r\nuv run pytest tests/test_core.py -v\r\n\r\n# Run with coverage (86% coverage, exceeds 80% target)\r\nuv run pytest tests/test_core.py --cov=src/ssh_agent_bridge --cov-report=html\r\n\r\n# Run core unit tests\r\nuv run pytest tests/test_core.py::TestDataTypes tests/test_core.py::TestExceptions tests/test_core.py::TestSSHService tests/test_core.py::TestConnectionManagement tests/test_core.py::TestSessionLifecycle tests/test_core.py::TestCommandExecution -v\r\n```\r\n\r\nFor detailed testing information, see:\r\n- **[TEST_RUNNER_STRATEGY.md](tests/TEST_RUNNER_STRATEGY.md)** - Safe test execution guide\r\n- **[TESTING_PATTERNS.md](tests/TESTING_PATTERNS.md)** - Patterns and anti-patterns\r\n\r\n## Project Status\r\n\r\n**Phase 6 Complete \u2705 | Released on PyPI \ud83d\ude80**\r\n\r\n### Current Phase: Phase 6 - Packaging & Release (COMPLETE)\r\n\r\n#### Phase 6 Completion\r\n- \u2705 **Build System:** PEP 517 build configured, wheel & sdist generation tested\r\n- \u2705 **PyPI Preparation:** Package metadata, classifiers, and documentation uploaded\r\n- \u2705 **Release Process:** Version 0.1.1 tagged and released to PyPI\r\n- \u2705 **Package Available:** https://pypi.org/project/ssh-agent-bridge/\r\n\r\n#### Final Test Status\r\n- \u2705 **55/55 core tests PASS** (100% pass rate)\r\n- \u2705 **86% Code Coverage** (exceeded 80% target)\r\n- \u2705 **7/7 Example Scripts** (all working successfully)\r\n- \u2705 **100% Core Functionality** (production ready)\r\n\r\n#### Next Phase: Phase 7 - Maintenance & Enhancements\r\n- \ufffd **User Feedback:** Collect issues and feature requests\r\n- \ud83d\udd27 **Maintenance:** Bug fixes and security updates\r\n- \u2728 **Future Features:** Connection multiplexing, advanced prompt detection, SFTP support\r\n- \ud83c\udf10 **Community:** Documentation improvements, contribution guidelines\r\n\r\n## Support\r\n\r\nIf you find this project helpful, please consider:\r\n\r\n- \u2b50 Starring the repository\r\n- \ud83d\udc1b Reporting bugs or issues\r\n- \ud83d\udca1 Suggesting features or improvements\r\n- \ud83d\udcd6 Contributing documentation\r\n\r\n## Related Projects\r\n\r\n- [asyncssh](https://github.com/ronf/asyncssh) - Underlying SSH protocol implementation\r\n- [paramiko](https://github.com/paramiko/paramiko) - Alternative SSH library for Python\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "High-level SSH session management for AI agents",
"version": "0.1.1",
"project_urls": {
"Changelog": "https://github.com/Ganzzi/ssh_agent_bridge/blob/main/CHANGELOG.md",
"Documentation": "https://ssh-agent-bridge.readthedocs.io/",
"Homepage": "https://github.com/Ganzzi/ssh_agent_bridge",
"Issues": "https://github.com/Ganzzi/ssh_agent_bridge/issues",
"Repository": "https://github.com/Ganzzi/ssh_agent_bridge.git"
},
"split_keywords": [
"ssh",
" async",
" agent",
" ai",
" session",
" command"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "8425e29e6dc670e16145c71b6cc2eb221d3229d118377dae764fb6ad140ddd16",
"md5": "502c79ee83e339109056ebfc9f3f5bf5",
"sha256": "997e03c5b34fd2223edfd9dee6f2f2b1cd071ec1572bcdf510a735bb20284044"
},
"downloads": -1,
"filename": "ssh_agent_bridge-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "502c79ee83e339109056ebfc9f3f5bf5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 13142,
"upload_time": "2025-10-26T15:16:10",
"upload_time_iso_8601": "2025-10-26T15:16:10.409154Z",
"url": "https://files.pythonhosted.org/packages/84/25/e29e6dc670e16145c71b6cc2eb221d3229d118377dae764fb6ad140ddd16/ssh_agent_bridge-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4f38e22a8a85bdb0189f8950c1e900dff3cf85c6456ded838c6b4907ed1abc34",
"md5": "c20867c0d95817de95874dc53fc5c2fe",
"sha256": "e303d89c5f2096132f1c839177a3c42ea25c170358c160796cff6f81e0460ec5"
},
"downloads": -1,
"filename": "ssh_agent_bridge-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "c20867c0d95817de95874dc53fc5c2fe",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 62839,
"upload_time": "2025-10-26T15:16:11",
"upload_time_iso_8601": "2025-10-26T15:16:11.727262Z",
"url": "https://files.pythonhosted.org/packages/4f/38/e22a8a85bdb0189f8950c1e900dff3cf85c6456ded838c6b4907ed1abc34/ssh_agent_bridge-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-26 15:16:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Ganzzi",
"github_project": "ssh_agent_bridge",
"github_not_found": true,
"lcname": "ssh-agent-bridge"
}
