webssh/AGENTS.md

Repository guidance

Project overview

WebSSH is a Python 3.10+ web SSH client. Tornado serves the HTTP and WebSocket endpoints, Paramiko manages SSH connections, and xterm.js renders the terminal in the browser.

Repository layout

• webssh/main.py: application entry point and route wiring.
• webssh/handler.py: HTTP/WebSocket handlers and SSH connection setup.
• webssh/worker.py: asynchronous relay between Tornado and Paramiko channels.
• webssh/settings.py: CLI options and application/server configuration.
• webssh/auth.py, webssh/storage.py, webssh/crypto.py: authentication and persistent saved-connection data.
• webssh/templates/ and webssh/static/: browser UI.
• tests/: pytest/unittest test suite; tests/sshserver.py provides the local Paramiko-based integration server.

Setup and development commands

Use Python 3.10, 3.11, or 3.12.

python -m pip install -r requirements.txt
python -m pip install -e .
python run.py                         # listens on 127.0.0.1:8888
python run.py --port=8888 --debug=True --data-dir=./data

Install test tools with python -m pip install pytest pytest-cov ruff. Before handing off a change, run the checks relevant to it:

python -m pytest tests
python -m pytest tests/test_app.py    # focused example
python -m pytest --cov=webssh
ruff check .

The legacy Flake8 configuration in setup.cfg uses a maximum line length of 79 and excludes tests and __init__.py files.

Implementation constraints

• Do not block Tornado's IOLoop. Paramiko connection work is blocking and must run through the existing handler ThreadPoolExecutor pattern.
• Preserve locking around auth data, saved connections, and host-key mutation; these objects are accessed from multiple threads.
• New HTTP endpoints should include MixinHandler. Protect private endpoints with @tornado.web.authenticated and retain the existing origin, XSRF, IP, and session checks.
• Treat credentials, private keys, cookie secrets, and saved connection data as sensitive. Never log or expose them to the browser. Persistent auth and connection files must retain mode 0o600.
• Keep saved-password encryption compatible with the cookie secret and do not silently reuse a credential when host, port, or username changes.
• Keep changes compatible with all supported Python versions and avoid adding dependencies unless the task requires them.

Testing expectations

• Add or update focused tests for behavior changes and regressions.
• Use the local mock SSH server for SSH authentication and connection flows; tests must not depend on external SSH hosts or network services.
• For frontend or WebSocket changes, cover both the server handler behavior and the corresponding browser-side message contract when applicable.
• Do not commit generated runtime state such as auth.json, connections.json, cookie secrets, coverage output, caches, or local data directories.