aircloud-cli 0.1.0__tar.gz → 0.2.0__tar.gz

aircloud_cli-0.2.0/PKG-INFO

@@ -0,0 +1,248 @@
+Metadata-Version: 2.4
+Name: aircloud-cli
+Version: 0.2.0
+Summary: AirCloud CLI — endpoint management, SSH, and container exec
+Author-email: AirCloud Team <support@aieev.com>
+License: Proprietary
+Project-URL: Homepage, https://aieev.com
+Project-URL: Repository, https://github.com/aieev/aircloud-cli
+Keywords: aircloud,ssh,cli,endpoint,exec
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Classifier: Topic :: System :: Shells
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: websockets>=12.0
+Requires-Dist: click>=8.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: paramiko>=3.0
+Requires-Dist: cryptography>=3.0
+
+# aircloud-cli
+
+CLI for the [AirCloud](https://aieev.com) platform — endpoint management,
+SSH access, and container shell exec.
+
+## Install
+
+```bash
+pip install aircloud-cli
+```
+
+Requires Python 3.9+.
+
+## Quick start
+
+```bash
+# one-time setup
+aircloud config set api-key <YOUR_API_KEY>
+aircloud config set api-base-url <API_BASE_URL>
+
+# inspect endpoints
+aircloud endpoints list
+aircloud endpoints get <endpoint_id>
+
+# open a shell in a container
+aircloud ssh <endpoint_id>            # public-key auth, sshd-based
+aircloud exec <endpoint_id>           # docker exec over WS, no sshd needed
+```
+
+## Commands
+
+### `aircloud config`
+
+Manage CLI configuration in `~/.aircloud/config.json`.
+
+```bash
+aircloud config set api-key <key>
+aircloud config set api-base-url <url>
+aircloud config list
+aircloud config get <key>
+```
+
+### `aircloud endpoints`
+
+```bash
+aircloud endpoints list                          # paged list
+aircloud endpoints get <id>                      # detail
+aircloud endpoints start <id>
+aircloud endpoints stop <id>
+aircloud endpoints scale <id> --replicas N
+aircloud endpoints patch <id> --command "..." --port 8080 --env KEY=VALUE
+aircloud endpoints replicas <id>                 # current replicas
+aircloud endpoints logs <id> [--replica-id X] [--start-line N --end-line M]
+```
+
+### `aircloud ssh`
+
+SSH into a container via WebSocket tunnel using public-key authentication.
+
+```bash
+aircloud ssh <endpoint_id>                       # auto-discover ~/.ssh/id_*
+aircloud ssh <endpoint_id> -i ~/.ssh/aircloud_key
+aircloud ssh <endpoint_id> -r <replica_id>       # pin to specific replica
+aircloud ssh <endpoint_id> --tunnel-only         # open tunnel only
+```
+
+Auto-discovers identity files in this order: `~/.ssh/id_ed25519`,
+`~/.ssh/id_ecdsa`, `~/.ssh/id_rsa`. Override with `-i / --identity-file`.
+
+The container image must have `sshd` running and consume the
+`AIRCLOUD_AUTHORIZED_KEYS` environment variable (AirCloud-provided template
+images do this by default).
+
+### `aircloud ssh-proxy` / `aircloud ssh-config` (VS Code Remote-SSH, scp, git)
+
+`aircloud ssh` opens its own tunnel and interactive shell. To use the
+system `ssh`, `scp`, `git`, or **VS Code Remote-SSH** instead — without
+pre-starting a tunnel or opening a local port — register `ssh-proxy` as an
+OpenSSH `ProxyCommand`.
+
+`ssh-proxy` bridges its own stdin/stdout to the WebSocket tunnel, so `ssh`
+spawns one automatically per connection and tears it down on disconnect.
+
+Install the config block into `~/.ssh/config`:
+
+```bash
+aircloud ssh-config <endpoint_id> -i ~/.ssh/id_ed25519 --install
+```
+
+`--install` writes the block between `# >>> aircloud managed: <id> >>>`
+markers, so it is idempotent (re-running replaces in place, never
+duplicates). It backs up `~/.ssh/config` first, resolves the absolute path
+to `aircloud` (so GUI-launched VS Code finds it regardless of `PATH`), and
+prepends the block above any catch-all `Host *` so its `User` / options win
+under SSH's first-match-wins rule. The installed block:
+
+```
+Host aircloud-<endpoint_id>
+    HostName <endpoint_id>
+    User root
+    IdentityFile ~/.ssh/id_ed25519
+    ProxyCommand /abs/path/to/aircloud ssh-proxy %h --stdio
+    ServerAliveInterval 30
+    ServerAliveCountMax 3
+    StrictHostKeyChecking accept-new
+```
+
+Run without `--install` to print the block for review instead of writing
+it, or with `--uninstall` to remove that endpoint's managed block.
+
+Then connect with any SSH-based tool:
+
+```bash
+ssh aircloud-<endpoint_id>
+scp file.txt aircloud-<endpoint_id>:/workspace/
+# VS Code: Remote-SSH → Connect to Host → aircloud-<endpoint_id>
+```
+
+`ServerAliveInterval` keeps the session alive past L7 proxy idle timeouts.
+The container image must run `sshd` (same requirement as `aircloud ssh`).
+
+Running `aircloud ssh-proxy <endpoint_id> --stdio` directly in a terminal
+only prints the server's SSH banner and then waits — it is a transport for
+an SSH client, not a shell. Drive it through `ssh` / `ProxyCommand`.
+
+#### Reconnection / transient relay slowness
+
+When the relay is briefly slow (heavy workload on the node), the WebSocket
+handshake can time out (`timed out during opening handshake`). `ssh-proxy`
+retries the connect with exponential backoff so a transient blip is absorbed
+instead of failing the connection. This applies to the **connect phase only**
+— once a session is bridged, a mid-session drop ends it (SSH cannot resume),
+and the client (VS Code, or you) reconnects, which spawns a fresh proxy that
+retries again.
+
+Tunables (env, read by `ssh-proxy`):
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `AIRCLOUD_SSH_OPEN_TIMEOUT` | `15` | Per-attempt WS handshake timeout (seconds) |
+| `AIRCLOUD_SSH_CONNECT_RETRIES` | `3` | Retry count for transient failures (timeout / 5xx) |
+
+Auth/routing failures (3xx/4xx) are not retried — they surface immediately.
+
+For VS Code, raise its own connect timeout so a single attempt can span the
+proxy's retries, in `settings.json`:
+
+```json
+"remote.SSH.connectTimeout": 60
+```
+
+### `aircloud exec`
+
+Open an interactive shell in the container via `docker exec` over a
+WebSocket. Works on any image — no `sshd` required.
+
+```bash
+aircloud exec <endpoint_id>
+aircloud exec <endpoint_id> -r <replica_id>      # pin replica
+aircloud exec <endpoint_id> -c "/bin/sh"         # custom command
+```
+
+### `aircloud whoami`
+
+Print the identity associated with the current API key.
+
+```bash
+aircloud whoami
+```
+
+## Development
+
+Editable install — source edits are picked up immediately by the
+`aircloud` command, no rebuild required:
+
+```bash
+pip install -e .
+aircloud --help
+```
+
+## Build & Release
+
+Published to PyPI as `aircloud-cli`. Requires `build` and `twine`
+(`pip install build twine`).
+
+```bash
+# 1. bump the version in pyproject.toml (PyPI rejects re-uploading a version)
+
+# 2. clean stale artifacts
+rm -rf dist
+
+# 3. build sdist + wheel into dist/
+python -m build
+
+# 4. upload to PyPI (needs a PyPI API token in ~/.pypirc or entered at the prompt)
+twine upload dist/*
+
+# 5. tag and push the release
+git commit -am "release(x.y.z): <summary>"
+git tag vx.y.z
+git push origin main --tags
+```
+
+Verify the published package in a clean environment:
+
+```bash
+python -m venv /tmp/ac && /tmp/ac/bin/pip install "aircloud-cli==x.y.z"
+/tmp/ac/bin/aircloud --help
+```
+
+## Status
+
+This is an early functional release. Interfaces may change before `1.0.0`.
+
+## License
+
+Proprietary. © AIEEV / AirCloud.

aircloud_cli-0.2.0/README.md

@@ -0,0 +1,217 @@
+# aircloud-cli
+
+CLI for the [AirCloud](https://aieev.com) platform — endpoint management,
+SSH access, and container shell exec.
+
+## Install
+
+```bash
+pip install aircloud-cli
+```
+
+Requires Python 3.9+.
+
+## Quick start
+
+```bash
+# one-time setup
+aircloud config set api-key <YOUR_API_KEY>
+aircloud config set api-base-url <API_BASE_URL>
+
+# inspect endpoints
+aircloud endpoints list
+aircloud endpoints get <endpoint_id>
+
+# open a shell in a container
+aircloud ssh <endpoint_id>            # public-key auth, sshd-based
+aircloud exec <endpoint_id>           # docker exec over WS, no sshd needed
+```
+
+## Commands
+
+### `aircloud config`
+
+Manage CLI configuration in `~/.aircloud/config.json`.
+
+```bash
+aircloud config set api-key <key>
+aircloud config set api-base-url <url>
+aircloud config list
+aircloud config get <key>
+```
+
+### `aircloud endpoints`
+
+```bash
+aircloud endpoints list                          # paged list
+aircloud endpoints get <id>                      # detail
+aircloud endpoints start <id>
+aircloud endpoints stop <id>
+aircloud endpoints scale <id> --replicas N
+aircloud endpoints patch <id> --command "..." --port 8080 --env KEY=VALUE
+aircloud endpoints replicas <id>                 # current replicas
+aircloud endpoints logs <id> [--replica-id X] [--start-line N --end-line M]
+```
+
+### `aircloud ssh`
+
+SSH into a container via WebSocket tunnel using public-key authentication.
+
+```bash
+aircloud ssh <endpoint_id>                       # auto-discover ~/.ssh/id_*
+aircloud ssh <endpoint_id> -i ~/.ssh/aircloud_key
+aircloud ssh <endpoint_id> -r <replica_id>       # pin to specific replica
+aircloud ssh <endpoint_id> --tunnel-only         # open tunnel only
+```
+
+Auto-discovers identity files in this order: `~/.ssh/id_ed25519`,
+`~/.ssh/id_ecdsa`, `~/.ssh/id_rsa`. Override with `-i / --identity-file`.
+
+The container image must have `sshd` running and consume the
+`AIRCLOUD_AUTHORIZED_KEYS` environment variable (AirCloud-provided template
+images do this by default).
+
+### `aircloud ssh-proxy` / `aircloud ssh-config` (VS Code Remote-SSH, scp, git)
+
+`aircloud ssh` opens its own tunnel and interactive shell. To use the
+system `ssh`, `scp`, `git`, or **VS Code Remote-SSH** instead — without
+pre-starting a tunnel or opening a local port — register `ssh-proxy` as an
+OpenSSH `ProxyCommand`.
+
+`ssh-proxy` bridges its own stdin/stdout to the WebSocket tunnel, so `ssh`
+spawns one automatically per connection and tears it down on disconnect.
+
+Install the config block into `~/.ssh/config`:
+
+```bash
+aircloud ssh-config <endpoint_id> -i ~/.ssh/id_ed25519 --install
+```
+
+`--install` writes the block between `# >>> aircloud managed: <id> >>>`
+markers, so it is idempotent (re-running replaces in place, never
+duplicates). It backs up `~/.ssh/config` first, resolves the absolute path
+to `aircloud` (so GUI-launched VS Code finds it regardless of `PATH`), and
+prepends the block above any catch-all `Host *` so its `User` / options win
+under SSH's first-match-wins rule. The installed block:
+
+```
+Host aircloud-<endpoint_id>
+    HostName <endpoint_id>
+    User root
+    IdentityFile ~/.ssh/id_ed25519
+    ProxyCommand /abs/path/to/aircloud ssh-proxy %h --stdio
+    ServerAliveInterval 30
+    ServerAliveCountMax 3
+    StrictHostKeyChecking accept-new
+```
+
+Run without `--install` to print the block for review instead of writing
+it, or with `--uninstall` to remove that endpoint's managed block.
+
+Then connect with any SSH-based tool:
+
+```bash
+ssh aircloud-<endpoint_id>
+scp file.txt aircloud-<endpoint_id>:/workspace/
+# VS Code: Remote-SSH → Connect to Host → aircloud-<endpoint_id>
+```
+
+`ServerAliveInterval` keeps the session alive past L7 proxy idle timeouts.
+The container image must run `sshd` (same requirement as `aircloud ssh`).
+
+Running `aircloud ssh-proxy <endpoint_id> --stdio` directly in a terminal
+only prints the server's SSH banner and then waits — it is a transport for
+an SSH client, not a shell. Drive it through `ssh` / `ProxyCommand`.
+
+#### Reconnection / transient relay slowness
+
+When the relay is briefly slow (heavy workload on the node), the WebSocket
+handshake can time out (`timed out during opening handshake`). `ssh-proxy`
+retries the connect with exponential backoff so a transient blip is absorbed
+instead of failing the connection. This applies to the **connect phase only**
+— once a session is bridged, a mid-session drop ends it (SSH cannot resume),
+and the client (VS Code, or you) reconnects, which spawns a fresh proxy that
+retries again.
+
+Tunables (env, read by `ssh-proxy`):
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `AIRCLOUD_SSH_OPEN_TIMEOUT` | `15` | Per-attempt WS handshake timeout (seconds) |
+| `AIRCLOUD_SSH_CONNECT_RETRIES` | `3` | Retry count for transient failures (timeout / 5xx) |
+
+Auth/routing failures (3xx/4xx) are not retried — they surface immediately.
+
+For VS Code, raise its own connect timeout so a single attempt can span the
+proxy's retries, in `settings.json`:
+
+```json
+"remote.SSH.connectTimeout": 60
+```
+
+### `aircloud exec`
+
+Open an interactive shell in the container via `docker exec` over a
+WebSocket. Works on any image — no `sshd` required.
+
+```bash
+aircloud exec <endpoint_id>
+aircloud exec <endpoint_id> -r <replica_id>      # pin replica
+aircloud exec <endpoint_id> -c "/bin/sh"         # custom command
+```
+
+### `aircloud whoami`
+
+Print the identity associated with the current API key.
+
+```bash
+aircloud whoami
+```
+
+## Development
+
+Editable install — source edits are picked up immediately by the
+`aircloud` command, no rebuild required:
+
+```bash
+pip install -e .
+aircloud --help
+```
+
+## Build & Release
+
+Published to PyPI as `aircloud-cli`. Requires `build` and `twine`
+(`pip install build twine`).
+
+```bash
+# 1. bump the version in pyproject.toml (PyPI rejects re-uploading a version)
+
+# 2. clean stale artifacts
+rm -rf dist
+
+# 3. build sdist + wheel into dist/
+python -m build
+
+# 4. upload to PyPI (needs a PyPI API token in ~/.pypirc or entered at the prompt)
+twine upload dist/*
+
+# 5. tag and push the release
+git commit -am "release(x.y.z): <summary>"
+git tag vx.y.z
+git push origin main --tags
+```
+
+Verify the published package in a clean environment:
+
+```bash
+python -m venv /tmp/ac && /tmp/ac/bin/pip install "aircloud-cli==x.y.z"
+/tmp/ac/bin/aircloud --help
+```
+
+## Status
+
+This is an early functional release. Interfaces may change before `1.0.0`.
+
+## License
+
+Proprietary. © AIEEV / AirCloud.

{aircloud_cli-0.1.0 → aircloud_cli-0.2.0}/aircloud_cli/main.py

@@ -6,9 +6,10 @@ from urllib.parse import urlparse, urlunparse
 import click
 
 from aircloud_cli import config
+from aircloud_cli import ssh_config as sshcfg
 from aircloud_cli.client import AirCloudAPIError, AirCloudClient, AirCloudError
 from aircloud_cli.container_exec import start_exec
-from aircloud_cli.ssh_tunnel import start_ssh, start_tunnel
+from aircloud_cli.ssh_tunnel import run_stdio_proxy, start_ssh, start_tunnel
 
 DEFAULT_SSH_HOST = "your-aircloud-host.example.com"
 
@@ -437,6 +438,151 @@ def ssh(
         )
 
 
+@cli.command("ssh-proxy")
+@click.argument("endpoint_id")
+@click.option(
+    "--stdio",
+    is_flag=True,
+    default=False,
+    help="Bridge stdin/stdout to the tunnel (for use as an ssh ProxyCommand).",
+)
+@click.option(
+    "--replica-id",
+    "-r",
+    default=None,
+    help="Pin the tunnel to a specific replica (default: load-balanced)",
+)
+@click.option(
+    "--host",
+    default=None,
+    help="Override host in the derived WS URL (default: inferred from endpoint)",
+)
+@click.option("--api-key", "-k", default=None, help="API key (default: from config)")
+def ssh_proxy(
+    endpoint_id: str,
+    stdio: bool,
+    replica_id: str | None,
+    host: str | None,
+    api_key: str | None,
+):
+    """Bridge the SSH tunnel over stdin/stdout for use as an ssh ProxyCommand.
+
+    Designed for ~/.ssh/config so ssh / scp / VS Code Remote-SSH work
+    without pre-starting a tunnel or opening a local port:
+
+    \b
+        Host aircloud-myendpoint
+            HostName <ENDPOINT_ID>
+            User root
+            ProxyCommand aircloud ssh-proxy %h --stdio
+            ServerAliveInterval 30
+
+    Then `ssh aircloud-myendpoint` (or VS Code Remote-SSH) connects and
+    ssh spawns this proxy automatically. In --stdio mode stdout carries
+    raw SSH bytes, so all messages are emitted on stderr.
+    """
+    resolved_api_key = api_key or config.get_api_key()
+    if not resolved_api_key:
+        raise click.ClickException(
+            "API key not set. Run: aircloud config set api-key <key>"
+        )
+
+    client = _get_client(api_key=resolved_api_key)
+    endpoint = client.get_endpoint(endpoint_id)
+    serving_url = endpoint.get("serving_endpoint_url")
+    if not serving_url:
+        raise click.ClickException(
+            "Endpoint is missing serving_endpoint_url; cannot build SSH tunnel URL."
+        )
+
+    parsed = urlparse(serving_url)
+    scheme = "wss" if parsed.scheme == "https" else "ws"
+    netloc = host or parsed.netloc
+    path = parsed.path.rstrip("/") + "/ssh/tunnel"
+    ws_url = urlunparse((scheme, netloc, path, "", "", ""))
+
+    click.echo(
+        f"aircloud ssh-proxy: tunneling to {endpoint_id} via {netloc}", err=True
+    )
+    run_stdio_proxy(ws_url, resolved_api_key, replica_id)
+
+
+@cli.command("ssh-config")
+@click.argument("endpoint_id")
+@click.option("--alias", default=None, help="Host alias (default: aircloud-<endpoint_id>)")
+@click.option("--user", "-u", default="root", show_default=True, help="SSH user")
+@click.option(
+    "--identity-file",
+    "-i",
+    default=None,
+    help="Path to SSH private key to pin in the config block",
+)
+@click.option(
+    "--install",
+    "do_install",
+    is_flag=True,
+    help="Write the managed block into ~/.ssh/config (idempotent, backs up first)",
+)
+@click.option(
+    "--uninstall",
+    "do_uninstall",
+    is_flag=True,
+    help="Remove the managed block for this endpoint from ~/.ssh/config",
+)
+def ssh_config(
+    endpoint_id: str,
+    alias: str | None,
+    user: str,
+    identity_file: str | None,
+    do_install: bool,
+    do_uninstall: bool,
+):
+    """Manage a ~/.ssh/config block that routes ssh/scp/VS Code through ssh-proxy.
+
+    With no flag the block is printed for review. --install writes it
+    idempotently between aircloud markers (backing up the file first and
+    using an absolute aircloud path so VS Code Remote-SSH can find it);
+    --uninstall removes that managed block.
+    """
+    if do_install and do_uninstall:
+        raise click.ClickException("Use only one of --install / --uninstall.")
+
+    host_alias = alias or f"aircloud-{endpoint_id}"
+
+    if do_uninstall:
+        path, removed, backup = sshcfg.uninstall(endpoint_id)
+        if removed:
+            click.echo(f"Removed aircloud block for {endpoint_id} from {path}")
+            if backup:
+                click.echo(f"Backup: {backup}")
+        else:
+            click.echo(f"No managed block for {endpoint_id} found in {path}")
+        return
+
+    aircloud_path = sshcfg.resolve_aircloud_path()
+
+    if do_install:
+        path, backup = sshcfg.install(
+            endpoint_id, host_alias, user, identity_file, aircloud_path
+        )
+        click.echo(f"Installed SSH config block into {path}")
+        if backup:
+            click.echo(f"Backup: {backup}")
+        click.echo(f"Connect:  ssh {host_alias}")
+        click.echo(f"VS Code:  Remote-SSH -> Connect to Host -> {host_alias}")
+        return
+
+    body = sshcfg.render_block(
+        endpoint_id, host_alias, user, identity_file, aircloud_path
+    )
+    click.echo(sshcfg.managed_block(endpoint_id, body).rstrip("\n"))
+    click.echo(
+        "\n# Append the block above to ~/.ssh/config, or rerun with --install.",
+        err=True,
+    )
+    click.echo(f"# Then: ssh {host_alias}", err=True)
+
+
 @cli.command("exec")
 @click.argument("endpoint_id")
 @click.option(