Bamboo SSH

This project currently provides a reusable PTY-backed shell session core and an optional FastAPI web terminal adapter. It is designed for local or otherwise trusted environments.

It is not an SSH transport layer yet. The current implementation launches a real shell on the host where the service runs.

Requires Python 3.12 or newer.

Full Documentation

See the documentation set in docs/:

• Project Overview
• Architecture
• Using the Core in Other Python Projects
• Setup and Run
• Docker Support
• API and WebSocket Protocol
• File Reference
• Testing
• Security and Limitations

Install Profiles

The package supports three install modes:

• pip install bamboo-ssh for the reusable core package
• pip install "bamboo-ssh[web]" for the FastAPI web terminal adapter
• pip install "bamboo-ssh[full]" for the web adapter plus built-in config-file auth helpers

From this checkout, install the matching local package profile with:

python -m pip install .
python -m pip install ".[web]"
python -m pip install ".[full]"

Use requirements.txt for contributor setup. It installs the editable project with the full and dev extras.

Make Targets

For local contributor and release helpers:

• make install creates .venv and installs requirements.txt
• make clean removes local build and test artifacts
• make build creates a source distribution and wheel in dist/
• make deploy builds and uploads dist/* to PyPI with twine

For make deploy, authenticate with PyPI first, typically with a token in TWINE_PASSWORD.

Quick Start

python3 -m venv .venv
. .venv/bin/activate
python -m pip install ".[full]"
bamboo-ssh auth init
bamboo-ssh serve --host 127.0.0.1 --port 8765

Open http://127.0.0.1:8765/.

If the default config file exists, bamboo-ssh serve loads it automatically. Use --config /path/to/config.toml to point at a different file.

Embedded Usage

Other Python projects can import the package without using the built-in web auth flow.

The complete guide is in Using the Core in Other Python Projects.

Use the core session API directly:

from bamboo_ssh.core.session import TerminalSession

session = TerminalSession.start(cols=80, rows=24)
session.write("printf 'hello\\n'\n")
session.close()

Or mount the web adapter inside another backend:

from bamboo_ssh.adapters.fastapi_app import create_app

terminal_app = create_app()
protected_terminal_app = create_app(config_path="/etc/bamboo-ssh/config.toml")

Built-In Auth

The standalone auth mode is intentionally simple:

• one admin username
• password hash stored in a TOML config file
• signed session cookie for the browser
• no database

Manage it with:

bamboo-ssh auth init
bamboo-ssh auth set-password
bamboo-ssh auth show-config-path

After login, the terminal page loads normally. POST /logout clears the session cookie and returns the browser to the login page.

Shell Startup Tuning

Web terminal shell sessions export WEB_TERMINAL=1.

If your shell startup files do expensive optional work such as loading large completion bundles, language managers, or interactive prompts, you can use that variable to skip them for browser terminal sessions while keeping a full login shell for normal terminal use.

Docker Quick Start

cp docker/.env.example docker/.env
docker compose -f docker/compose.yml --env-file docker/.env up --build

This runs the terminal inside a Python 3.12 container. The browser terminal connects to the shell inside the container, not the host machine shell.