Metadata-Version: 2.4
Name: bamboo-ssh
Version: 0.1.0
Summary: Reusable terminal session core with optional web terminal extras.
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Provides-Extra: web
Requires-Dist: fastapi<1,>=0.136; extra == "web"
Requires-Dist: uvicorn<1,>=0.44; extra == "web"
Requires-Dist: websockets<17,>=13; extra == "web"
Provides-Extra: full
Requires-Dist: fastapi<1,>=0.136; extra == "full"
Requires-Dist: uvicorn<1,>=0.44; extra == "full"
Requires-Dist: websockets<17,>=13; extra == "full"
Requires-Dist: argon2-cffi<24.0,>=23.1; extra == "full"
Provides-Extra: dev
Requires-Dist: pytest==9.0.3; extra == "dev"
Requires-Dist: httpx==0.28.1; extra == "dev"

# 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/`](./docs/README.md):

- [Project Overview](./docs/project-overview.md)
- [Architecture](./docs/architecture.md)
- [Setup and Run](./docs/setup-and-run.md)
- [Docker Support](./docs/docker.md)
- [API and WebSocket Protocol](./docs/api-reference.md)
- [File Reference](./docs/file-reference.md)
- [Testing](./docs/testing.md)
- [Security and Limitations](./docs/security-and-limitations.md)

## 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:

```bash
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

```bash
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.

Use the core session API directly:

```python
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:

```python
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:

```bash
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

```bash
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.
