portacode 1.4.12.dev1__py3-none-any.whl → 1.4.15.dev3__py3-none-any.whl

portacode/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '1.4.12.dev1'
-__version_tuple__ = version_tuple = (1, 4, 12, 'dev1')
+__version__ = version = '1.4.15.dev3'
+__version_tuple__ = version_tuple = (1, 4, 15, 'dev3')
 
 __commit_id__ = commit_id = None

portacode/connection/handlers/WEBSOCKET_PROTOCOL.md

@@ -326,9 +326,12 @@ Configures a Proxmox node for Portacode infrastructure usage (API token validati
 
 **Payload Fields:**
 
-*   `token_identifier` (string, required): API token identifier in the form `user@realm!tokenid`.
-*   `token_value` (string, required): Secret value associated with the token.
-*   `verify_ssl` (boolean, optional): When true, the handler verifies SSL certificates; defaults to `false`.
+*   `token_identifier` (string, optional when reconfiguring): API token identifier in the form `user@realm!tokenid`. Required on first configuration or when replacing the stored token.
+*   `token_value` (string, optional when reconfiguring): Secret value associated with the token. Required when `token_identifier` is supplied.
+*   `verify_ssl` (boolean, optional): When true, the handler verifies SSL certificates; defaults to `false`. When omitted, the last configured value is preserved.
+*   `cloudflare_api_token` (string, optional): Cloudflare API token the host can reuse later to provision tunnels.
+
+The setup command also installs `cloudflared` on the node so Cloudflare tunnels can be created afterward.
 
 **Responses:**
 
@@ -361,6 +364,9 @@ Creates a Portacode-managed LXC container, starts it, and bootstraps the Portaco
 *   `username` (string, optional): OS user to provision (defaults to `svcuser`).
 *   `password` (string, optional): Password for the user (used only during provisioning).
 *   `ssh_key` (string, optional): SSH public key to add to the user.
+*   `device_id` (string, optional): ID of the Device record that already exists on the dashboard.
+*   `device_public_key` (string, optional): PEM-encoded Portacode public key. When supplied together with `device_private_key` the handler injects the keypair, records the device metadata, and runs `portacode service install` automatically.
+*   `device_private_key` (string, optional): PEM-encoded private key that pairs with `device_public_key`. Both key fields must be present for the automatic service-install mode.
 
 **Responses:**
 
@@ -406,6 +412,51 @@ Deletes a managed container from Proxmox (stopping it first if necessary) and re
 *   Emits a [`proxmox_container_action`](#proxmox_container_action-event) event with `action="remove"` and the refreshed infra snapshot after deletion.
 *   Emits an [`error`](#error) event on failure.
 
+### `create_cloudflare_tunnel`
+
+Creates or updates a Cloudflare tunnel in front of a managed container. The container must be running and a Cloudflare API token must already be configured via `setup_proxmox_infra`.
+
+**Payload Fields:**
+
+*   `ctid` (string, required): Identifier of the container.
+*   `container_port` (integer, required): Port inside the container to expose through Cloudflare.
+*   `cloudflare_url` (string, optional): Hostname (e.g., `app.example.com`) that the tunnel should serve. Leave blank to let Cloudflare create a quick tunnel (`*.cfargotunnel.com`) automatically.
+*   `protocol` (string, optional): One of `http`, `https`, or `tcp` (defaults to `http`).
+
+**Responses:**
+
+*   Emits a [`cloudflare_tunnel_created`](#cloudflare_tunnel_created-event) event with the tunnel metadata, the refreshed infra snapshot, and the optional `device_id` so dashboards can refresh the CT list.
+*   Emits an [`error`](#error) event on failure.
+
+### `update_cloudflare_tunnel`
+
+Refreshes the tunnel configuration for an existing tunnel (different port, URL, or protocol).
+
+**Payload Fields:**
+
+*   `ctid` (string, required): Identifier of the container.
+*   `container_port` (integer, optional): New container port.
+*   `cloudflare_url` (string, optional): New hostname (leave blank to keep the current hostname or let Cloudflare assign a quick tunnel).
+*   `protocol` (string, optional): New protocol (`http`, `https`, or `tcp`).
+
+**Responses:**
+
+*   Emits a [`cloudflare_tunnel_updated`](#cloudflare_tunnel_updated-event) event with the refreshed tunnel metadata, the refreshed infra snapshot, and the optional `device_id`.
+*   Emits an [`error`](#error) event on failure.
+
+### `remove_cloudflare_tunnel`
+
+Stops and removes any tunnel metadata associated with a container.
+
+**Payload Fields:**
+
+*   `ctid` (string, required): Identifier of the container.
+
+**Responses:**
+
+*   Emits a [`cloudflare_tunnel_removed`](#cloudflare_tunnel_removed-event) event with the refreshed infra snapshot and optional `device_id`.
+*   Emits an [`error`](#error) event on failure.
+
 ### `proxmox_container_created`
 
 Emitted after a successful `create_proxmox_container` action. Contains the new container ID, the Portacode public key produced inside the container, and the bootstrap logs.
@@ -418,6 +469,8 @@ Emitted after a successful `create_proxmox_container` action. Contains the new c
 *   `public_key` (string): Portacode public auth key created inside the new container.
 *   `container` (object): Metadata such as `vmid`, `hostname`, `template`, `storage`, `disk_gib`, `ram_mib`, and `cpus`.
 *   `setup_steps` (array[object]): Detailed bootstrap step results (name, stdout/stderr, elapsed time, and status).
+*   `device_id` (string, optional): Mirrors the `device_id` supplied with `create_proxmox_container`, if any.
+*   `service_installed` (boolean): True when the handler already ran `portacode service install` (with a provided keypair); otherwise it remains False and the dashboard can call `start_portacode_service`.
 
 ### `proxmox_container_progress`
 
@@ -450,6 +503,7 @@ Runs `sudo portacode service install` inside the container after the dashboard h
 *   Emits additional [`proxmox_container_progress`](#proxmox_container_progress-event) events to report the authentication and service-install steps.
 *   On success, emits a [`proxmox_service_started`](#proxmox_service_started-event).
 *   On failure, emits a generic [`error`](#error) event.
+*   When `create_proxmox_container` already provided a dashboard-generated keypair, the handler may have installed the service already, so this call is optional unless you need to re-run the install.
 
 ### `proxmox_service_started`
 
@@ -1120,6 +1174,8 @@ Provides system information in response to a `system_info` action. Handled by [`
                     *   `message` (string|null): Informational text about the network setup attempt.
                     *   `bridge` (string): The bridge interface configured (typically `vmbr1`).
                     *   `health` (string|null): `"healthy"` when the connectivity verification succeeded.
+                *   `cloudflare` (object): Optional Cloudflare metadata collected for future tunnels:
+                    *   `configured` (boolean): True when a Cloudflare API token is stored.
                 *   `node_status` (object|null): Status response returned by the Proxmox API when validating the token.
                 *   `managed_containers` (object): Cached summary of the Portacode-managed containers:
                     *   `updated_at` (string): ISO timestamp when this snapshot was last refreshed.
@@ -1137,6 +1193,11 @@ Provides system information in response to a `system_info` action. Handled by [`
                         *   `cpu_share` (number): vCPU-equivalent share requested at creation.
                         *   `status` (string): Lowercase lifecycle status (e.g., `running`, `stopped`, `deleted`).
                         *   `created_at` (string|null): ISO timestamp recorded when the CT was provisioned.
+                        *   `tunnel` (object|null): Tunnel metadata that includes:
+                            *   `url` (string): Public hostname assigned for this tunnel.
+                            *   `container_port` (integer): Container port exposed via the tunnel.
+                            *   `protocol` (string): Protocol advertised when the tunnel was configured.
+                            *   `status` (string): `running`, `stopped`, or `unknown`.
     *   `portacode_version` (string): Installed CLI version returned by `portacode.__version__`.
 
 ### `proxmox_infra_configured`
@@ -1202,6 +1263,48 @@ Emitted after `start_proxmox_container`, `stop_proxmox_container`, or `remove_pr
 *   `details` (object, optional): Exit status information (e.g., `exitstatus`, `stop_exitstatus`, `delete_exitstatus`).
 *   `infra` (object): Same snapshot described under [`system_info`](#system_info-event) `proxmox.infra`, including the updated `managed_containers` summary.
 
+### `cloudflare_tunnel_created`
+
+Submitted after a successful `create_cloudflare_tunnel` action.
+
+**Event Fields:**
+
+*   `event` (string): `cloudflare_tunnel_created`.
+*   `ctid` (string): Container ID associated with the tunnel.
+*   `success` (boolean): True when the tunnel is running.
+*   `device_id` (string, optional): Mirrors the `device_id` supplied with the command, letting dashboards refresh that device immediately.
+*   `message` (string): Summary text; when a hostname was assigned (including Quick Tunnel), the host is appended (e.g., `Created ... -> example.com`).
+*   `tunnel` (object): Tunnel metadata matching the manager view. When using Cloudflare Quick Tunnel (no hostname supplied), `tunnel.url` holds the autogenerated `*.cfargotunnel.com` hostname.
+*   `infra` (object): Snapshot produced by `get_infra_snapshot`, including the refreshed `managed_containers` list.
+
+### `cloudflare_tunnel_updated`
+
+Sent when `update_cloudflare_tunnel` completes.
+
+**Event Fields:**
+
+*   `event` (string): `cloudflare_tunnel_updated`.
+*   `ctid` (string): Container ID associated with the tunnel.
+*   `success` (boolean): True on success.
+*   `device_id` (string, optional): Mirrors the command's `device_id`.
+*   `message` (string): Summary text; includes the new hostname when one was assigned or changed.
+*   `tunnel` (object): Updated tunnel metadata.
+*   `infra` (object): Snapshot produced by `get_infra_snapshot` so dashboards can refresh the managed container list.
+
+### `cloudflare_tunnel_removed`
+
+Sent after a tunnel has been removed from a container record.
+
+**Event Fields:**
+
+*   `event` (string): `cloudflare_tunnel_removed`.
+*   `ctid` (string): Container ID that no longer has a tunnel.
+*   `success` (boolean): True on success.
+*   `device_id` (string, optional): Mirrors the command's `device_id`.
+*   `message` (string): Summary text.
+*   `tunnel` (null): Always `null` to explicitly clear the stored tunnel metadata.
+*   `infra` (object): The refreshed snapshot so dashboards see the updated container list.
+
 ### <a name="clock_sync_response"></a>`clock_sync_response`
 
 Reply sent by the gateway immediately after receiving a `clock_sync_request`. Devices use this event plus the measured round-trip time to keep their local `ntp_clock` offset accurate.

portacode/connection/handlers/__init__.py

@@ -43,12 +43,15 @@ from .project_state_handlers import (
 )
 from .proxmox_infra import (
     ConfigureProxmoxInfraHandler,
+    CreateCloudflareTunnelHandler,
     CreateProxmoxContainerHandler,
     RevertProxmoxInfraHandler,
     StartPortacodeServiceHandler,
     StartProxmoxContainerHandler,
     StopProxmoxContainerHandler,
+    RemoveCloudflareTunnelHandler,
     RemoveProxmoxContainerHandler,
+    UpdateCloudflareTunnelHandler,
 )
 
 __all__ = [
@@ -62,6 +65,7 @@ __all__ = [
     "TerminalListHandler",
     "SystemInfoHandler",
     "ConfigureProxmoxInfraHandler",
+    "CreateCloudflareTunnelHandler",
     "CreateProxmoxContainerHandler",
     # File operation handlers (optional - register as needed)
     "FileReadHandler",
@@ -91,7 +95,9 @@ __all__ = [
     "StartPortacodeServiceHandler",
     "StartProxmoxContainerHandler",
     "StopProxmoxContainerHandler",
+    "RemoveCloudflareTunnelHandler",
     "RemoveProxmoxContainerHandler",
+    "UpdateCloudflareTunnelHandler",
     "UpdatePortacodeHandler",
     "RevertProxmoxInfraHandler",
 ]