ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.
Python astracloudflarecontrol-panelcyberpaneldnsfablehosting-control-panelhosting-panelkimi-k3server-managementserverkitubuntu-web-panelwebserver
Split servers.py into area modules
Juan Denis166e9acabf32
diff --git a/backend/app/api/servers.py b/backend/app/api/servers.pyindex 8e0adbf6..2976a95b 100644--- a/backend/app/api/servers.py+++ b/backend/app/api/servers.py@@ -5,12 +5,10 @@ Endpoints for managing remote servers and their agents."""import os-import reimport hashlibimport hmac-import requestsfrom datetime import datetime, timedelta-from flask import Blueprint, request, jsonify, Response, current_app, redirect+from flask import Blueprint, request, jsonify, current_appfrom flask_jwt_extended import jwt_required, get_jwt_identityfrom sqlalchemy.orm import joinedload@@ -18,18 +16,19 @@ from app import db, limiterfrom app.services.server_metrics_service import latest_metrics_by_serverfrom app.api._query import apply_query, QueryParseErrorfrom app.api._request import json_object-from app.models import User-from app.models.server import Server, ServerGroup, ServerMetrics, ServerCommand, AgentSession, AgentVersion, AgentRollout+from app.models.server import Server, ServerGroup, ServerMetrics, ServerCommand, AgentSessionfrom app.services.agent_registry import agent_registryfrom app.services.remote_command_dispatcher import dispatch_agent_command-from app.services.agent_fleet_service import fleet_service-from app.services.discovery_service import discovery_servicefrom app.services import connection_string as connection_string_codecfrom app.middleware.rbac import admin_required, auth_required, developer_required, get_current_userfrom app.middleware.api_scope_middleware import require_scopefrom app.exceptions import (PermissionDeniedError, ValidationError, agent_offline, field_required, not_found,)+from app.utils.ip_utils import validate_ip_pattern+from app.models.security_alert import SecurityAlert+from app.services.anomaly_detection_service import anomaly_detection_service+from app.services.server_metrics_service import ServerMetricsService# Default token lifetime when the caller doesn't specify one. 7 days is@@ -1021,10 +1020,6 @@ def get_permission_profiles():# ==================== Security Features ====================-from app.utils.ip_utils import is_ip_allowed, validate_ip_pattern-from app.models.security_alert import SecurityAlert-from app.services.anomaly_detection_service import anomaly_detection_service-@servers_bp.route('/<server_id>/allowed-ips', methods=['GET'])@jwt_required()@@ -1259,446 +1254,6 @@ def resolve_alert(alert_id):return jsonify(alert.to_dict())-# ==================== Remote Docker Operations ====================--from app.services.remote_docker_service import RemoteDockerService-from app.services.server_metrics_service import ServerMetricsService-from app.services.terminal_service import TerminalService---@servers_bp.route('/available', methods=['GET'])-@jwt_required()-def get_available_servers():- """Get list of servers available for Docker operations"""- servers = RemoteDockerService.get_available_servers()- return jsonify(servers)---@servers_bp.route('/<server_id>/docker/containers', methods=['GET'])-@jwt_required()-def list_remote_containers(server_id):- """List containers on a remote server"""- all_containers = request.args.get('all', 'false').lower() == 'true'- user_id = get_jwt_identity()-- result = RemoteDockerService.list_containers(server_id, all=all_containers, user_id=user_id)-- if not result.get('success'):- return jsonify(result), _agent_failure_status(result)-- return jsonify(result.get('data', []))---@servers_bp.route('/<server_id>/docker/containers/<container_id>', methods=['GET'])-@jwt_required()-def inspect_remote_container(server_id, container_id):- """Inspect a container on a remote server"""- user_id = get_jwt_identity()-- result = RemoteDockerService.inspect_container(server_id, container_id, user_id=user_id)-- if not result.get('success'):- return jsonify(result), _agent_failure_status(result)-- return jsonify(result.get('data'))---@servers_bp.route('/<server_id>/docker/containers/<container_id>/start', methods=['POST'])-@developer_required-def start_remote_container(server_id, container_id):- """Start a container on a remote server"""- user_id = get_jwt_identity()-- result = RemoteDockerService.start_container(server_id, container_id, user_id=user_id)-- if not result.get('success'):- return jsonify(result), _agent_failure_status(result)-- return jsonify({'message': 'Container started'})---@servers_bp.route('/<server_id>/docker/containers/<container_id>/stop', methods=['POST'])-@developer_required-def stop_remote_container(server_id, container_id):- """Stop a container on a remote server"""- user_id = get_jwt_identity()- data = request.get_json() or {}- timeout = data.get('timeout')-- result = RemoteDockerService.stop_container(server_id, container_id, timeout=timeout, user_id=user_id)-- if not result.get('success'):- return jsonify(result), _agent_failure_status(result)-- return jsonify({'message': 'Container stopped'})---@servers_bp.route('/<server_id>/docker/containers/<container_id>/restart', methods=['POST'])-@developer_required-def restart_remote_container(server_id, container_id):- """Restart a container on a remote server"""- user_id = get_jwt_identity()- data = request.get_json() or {}- timeout = data.get('timeout')-- result = RemoteDockerService.restart_container(server_id, container_id, timeout=timeout, user_id=user_id)-- if not result.get('success'):- return jsonify(result), _agent_failure_status(result)-- return jsonify({'message': 'Container restarted'})---@servers_bp.route('/<server_id>/docker/containers/<container_id>', methods=['DELETE'])-@developer_required-def remove_remote_container(server_id, container_id):- """Remove a container on a remote server"""- user_id = get_jwt_identity()- force = request.args.get('force', 'false').lower() == 'true'- remove_volumes = request.args.get('v', 'false').lower() == 'true'-- result = RemoteDockerService.remove_container(- server_id, container_id,- force=force, remove_volumes=remove_volumes,- user_id=user_id- )-- if not result.get('success'):- return jsonify(result), _agent_failure_status(result)-- return jsonify({'message': 'Container removed'})---@servers_bp.route('/<server_id>/docker/containers/<container_id>/stats', methods=['GET'])-@jwt_required()-def get_remote_container_stats(server_id, container_id):- """Get container stats from a remote server"""- user_id = get_jwt_identity()-- result = RemoteDockerService.get_container_stats(server_id, container_id, user_id=user_id)-- if not result.get('success'):- return jsonify(result), _agent_failure_status(result)-- return jsonify(result.get('data'))---@servers_bp.route('/<server_id>/docker/containers/<container_id>/logs', methods=['GET'])-@jwt_required()-def get_remote_container_logs(server_id, container_id):- """- Get container logs from a remote server.-- Query params:- tail: Number of lines (default 100, 'all' for all lines)- since: Show logs since timestamp- timestamps: Include timestamps (default true)- """- user_id = get_jwt_identity()- tail = request.args.get('tail', '100')- since = request.args.get('since')- timestamps = request.args.get('timestamps', 'true').lower() == 'true'-- result = RemoteDockerService.get_container_logs(- server_id, container_id,- tail=tail, since=since, timestamps=timestamps,- user_id=user_id- )-- if not result.get('success'):- return jsonify(result), _agent_failure_status(result)-- return jsonify(result.get('data'))---@servers_bp.route('/<server_id>/docker/images', methods=['GET'])-@jwt_required()-def list_remote_images(server_id):- """List images on a remote server"""- user_id = get_jwt_identity()-- result = RemoteDockerService.list_images(server_id, user_id=user_id)-- if not result.get('success'):- return jsonify(result), _agent_failure_status(result)-- return jsonify(result.get('data', []))---@servers_bp.route('/<server_id>/docker/images/pull', methods=['POST'])-@developer_required-def pull_remote_image(server_id):- """Pull an image on a remote server"""- user_id = get_jwt_identity()- data = request.get_json()-- if not data or not data.get('image'):- return jsonify({'error': 'Image name required'}), 400-- result = RemoteDockerService.pull_image(server_id, data['image'], user_id=user_id)-- if not result.get('success'):- return jsonify(result), _agent_failure_status(result)-- return jsonify(result)---@servers_bp.route('/<server_id>/docker/images/<image_id>', methods=['DELETE'])-@developer_required-def remove_remote_image(server_id, image_id):- """Remove an image on a remote server"""- user_id = get_jwt_identity()- force = request.args.get('force', 'false').lower() == 'true'-- result = RemoteDockerService.remove_image(server_id, image_id, force=force, user_id=user_id)-- if not result.get('success'):- return jsonify(result), _agent_failure_status(result)-- return jsonify({'message': 'Image removed'})---@servers_bp.route('/<server_id>/docker/volumes', methods=['GET'])-@jwt_required()-def list_remote_volumes(server_id):- """List volumes on a remote server"""- user_id = get_jwt_identity()-- result = RemoteDockerService.list_volumes(server_id, user_id=user_id)-- if not result.get('success'):- return jsonify(result), _agent_failure_status(result)-- return jsonify(result.get('data', []))---@servers_bp.route('/<server_id>/docker/volumes/<volume_name>', methods=['DELETE'])-@developer_required-def remove_remote_volume(server_id, volume_name):- """Remove a volume on a remote server"""- user_id = get_jwt_identity()- force = request.args.get('force', 'false').lower() == 'true'-- result = RemoteDockerService.remove_volume(server_id, volume_name, force=force, user_id=user_id)-- if not result.get('success'):- return jsonify(result), _agent_failure_status(result)-- return jsonify({'message': 'Volume removed'})---@servers_bp.route('/<server_id>/docker/networks', methods=['GET'])-@jwt_required()-def list_remote_networks(server_id):- """List networks on a remote server"""- user_id = get_jwt_identity()-- result = RemoteDockerService.list_networks(server_id, user_id=user_id)-- if not result.get('success'):- return jsonify(result), _agent_failure_status(result)-- return jsonify(result.get('data', []))---@servers_bp.route('/<server_id>/docker/networks/<network_id>', methods=['DELETE'])-@developer_required-def remove_remote_network(server_id, network_id):- """Remove a network on a remote server"""- user_id = get_jwt_identity()-- result = RemoteDockerService.remove_network(server_id, network_id, user_id=user_id)-- if not result.get('success'):- return jsonify(result), _agent_failure_status(result)-- return jsonify({'message': 'Network removed'})---@servers_bp.route('/<server_id>/system/metrics', methods=['GET'])-@jwt_required()-def get_remote_system_metrics(server_id):- """Get system metrics from a remote server"""- user_id = get_jwt_identity()-- result = RemoteDockerService.get_system_metrics(server_id, user_id=user_id)-- if not result.get('success'):- return jsonify(result), _agent_failure_status(result)-- return jsonify(result.get('data'))---@servers_bp.route('/<server_id>/system/info', methods=['GET'])-@jwt_required()-def get_remote_system_info(server_id):- """Get system info from a remote server"""- user_id = get_jwt_identity()-- result = RemoteDockerService.get_system_info(server_id, user_id=user_id)-- if not result.get('success'):- return jsonify(result), _agent_failure_status(result)-- return jsonify(result.get('data'))---# ==================== Remote Docker Compose Operations ====================--@servers_bp.route('/<server_id>/docker/compose/projects', methods=['GET'])-@jwt_required()-def list_remote_compose_projects(server_id):- """List compose projects on a remote server"""- user_id = get_jwt_identity()-- result = RemoteDockerService.compose_list(server_id, user_id=user_id)-- if not result.get('success'):- return jsonify(result), _agent_failure_status(result)-- return jsonify(result.get('data', []))---@servers_bp.route('/<server_id>/docker/compose/ps', methods=['POST'])-@developer_required-def remote_compose_ps(server_id):- """List containers for a compose project"""- user_id = get_jwt_identity()- data = request.get_json()-- if not data or not data.get('project_path'):- raise field_required('project_path')-- result = RemoteDockerService.compose_ps(- server_id,- data['project_path'],- user_id=user_id- )-- if not result.get('success'):- return jsonify(result), _agent_failure_status(result)-- return jsonify(result.get('data', []))---@servers_bp.route('/<server_id>/docker/compose/up', methods=['POST'])-@developer_required-def remote_compose_up(server_id):- """Start a compose project"""- user_id = get_jwt_identity()- data = request.get_json()-- if not data or not data.get('project_path'):- raise field_required('project_path')-- result = RemoteDockerService.compose_up(- server_id,- data['project_path'],- detach=data.get('detach', True),- build=data.get('build', False),- user_id=user_id- )-- if not result.get('success'):- return jsonify(result), _agent_failure_status(result)-- return jsonify(result)---@servers_bp.route('/<server_id>/docker/compose/down', methods=['POST'])-@developer_required-def remote_compose_down(server_id):- """Stop a compose project"""- user_id = get_jwt_identity()- data = request.get_json()-- if not data or not data.get('project_path'):- raise field_required('project_path')-- result = RemoteDockerService.compose_down(- server_id,- data['project_path'],- volumes=data.get('volumes', False),- remove_orphans=data.get('remove_orphans', True),- user_id=user_id- )-- if not result.get('success'):- return jsonify(result), _agent_failure_status(result)-- return jsonify(result)---@servers_bp.route('/<server_id>/docker/compose/logs', methods=['POST'])-@developer_required-def remote_compose_logs(server_id):- """Get logs from a compose project"""- user_id = get_jwt_identity()- data = request.get_json()-- if not data or not data.get('project_path'):- raise field_required('project_path')-- result = RemoteDockerService.compose_logs(- server_id,- data['project_path'],- service=data.get('service'),- tail=data.get('tail', 100),- user_id=user_id- )-- if not result.get('success'):- return jsonify(result), _agent_failure_status(result)-- return jsonify(result.get('data'))---@servers_bp.route('/<server_id>/docker/compose/restart', methods=['POST'])-@developer_required-def remote_compose_restart(server_id):- """Restart a compose project or specific service"""- user_id = get_jwt_identity()- data = request.get_json()-- if not data or not data.get('project_path'):- raise field_required('project_path')-- result = RemoteDockerService.compose_restart(- server_id,- data['project_path'],- service=data.get('service'),- user_id=user_id- )-- if not result.get('success'):- return jsonify(result), _agent_failure_status(result)-- return jsonify(result)---@servers_bp.route('/<server_id>/docker/compose/pull', methods=['POST'])-@developer_required-def remote_compose_pull(server_id):- """Pull images for a compose project"""- user_id = get_jwt_identity()- data = request.get_json()-- if not data or not data.get('project_path'):- raise field_required('project_path')-- result = RemoteDockerService.compose_pull(- server_id,- data['project_path'],- service=data.get('service'),- user_id=user_id- )-- if not result.get('success'):- return jsonify(result), _agent_failure_status(result)-- return jsonify(result)--# ==================== Historical Metrics ====================@servers_bp.route('/<server_id>/metrics/history', methods=['GET'])@@ -1750,1286 +1305,5 @@ def trigger_metrics_cleanup():})-# ==================== Remote Terminal ====================--@servers_bp.route('/<server_id>/terminal', methods=['POST'])-@developer_required-def create_terminal_session(server_id):- """Create a new terminal session on a remote server.-- Body:- cols: Terminal width (default: 80)- rows: Terminal height (default: 24)- """- _get_operable_server(server_id)- user_id = get_jwt_identity()- data = request.get_json() or {}-- cols = data.get('cols', 80)- rows = data.get('rows', 24)-- result = TerminalService.create_session(- server_id=server_id,- user_id=user_id,- cols=cols,- rows=rows- )-- if not result.get('success'):- return jsonify(result), _agent_failure_status(result)-- return jsonify(result)---@servers_bp.route('/terminal/<session_id>/input', methods=['POST'])-@developer_required-def terminal_input(session_id):- """Send input to a terminal session.-- Body:- data: Base64-encoded input data- """- user_id = get_jwt_identity()- data = request.get_json()-- if not data or not data.get('data'):- raise field_required('data')-- result = TerminalService.send_input(- session_id=session_id,- data=data['data'],- user_id=user_id- )-- if not result.get('success'):- return jsonify(result), 400-- return jsonify(result)---@servers_bp.route('/terminal/<session_id>/resize', methods=['POST'])-@developer_required-def terminal_resize(session_id):- """Resize a terminal session.-- Body:- cols: New terminal width- rows: New terminal height- """- user_id = get_jwt_identity()- data = request.get_json()-- if not data or not data.get('cols') or not data.get('rows'):- return jsonify({'error': 'cols and rows are required'}), 400-- result = TerminalService.resize_session(- session_id=session_id,- cols=data['cols'],- rows=data['rows'],- user_id=user_id- )-- if not result.get('success'):- return jsonify(result), 400-- return jsonify(result)---@servers_bp.route('/terminal/<session_id>', methods=['DELETE'])-@developer_required-def close_terminal_session(session_id):- """Close a terminal session."""- user_id = get_jwt_identity()-- result = TerminalService.close_session(- session_id=session_id,- user_id=user_id- )-- if not result.get('success'):- return jsonify(result), 400-- return jsonify(result)---@servers_bp.route('/terminal/sessions', methods=['GET'])-@jwt_required()-def list_terminal_sessions():- """List all terminal sessions for the current user."""- user_id = get_jwt_identity()-- sessions = TerminalService.get_user_sessions(user_id)- return jsonify({- 'sessions': sessions,- 'count': len(sessions)- })---# ==================== Installation Scripts ====================--def _get_scripts_dir():- """Resolve the directory holding the fleet-agent installer scripts.-- Every shipped layout has to land on a real directory here:-- * git checkout / release tarball -> ``<tree root>/scripts``- * Docker image -> ``/app/scripts``, which exists only- because the Dockerfile explicitly copies the two installers there.-- ``SERVERKIT_SCRIPTS_DIR`` overrides the guess for layouts that split the- backend away from the rest of the tree.- """- override = os.environ.get('SERVERKIT_SCRIPTS_DIR')- if override:- return override- # Go up from backend/app/api to backend, then to scripts- base_dir = os.path.dirname(os.path.dirname(os.path.dirname(os.path.dirname(__file__))))- return os.path.join(base_dir, 'scripts')---def _load_installer(filename):- """Read an agent installer off disk and stamp this panel's coordinates in.-- Returns ``(content, None)`` on success or ``(None, error_response)`` when the- file is absent, so the two endpoints below cannot drift apart.- """- script_path = os.path.join(_get_scripts_dir(), filename)-- if not os.path.exists(script_path):- # A missing installer is a packaging fault on THIS panel, never a bad- # request. The old 404 asserted "no such URL", which is exactly what sent- # issue #101's reporter hunting for a wrong path -- they filed it as- # "incorrect paths in setup" -- when the file had simply never been- # shipped into the image. 503 says "this server is broken, not your URL",- # and the log line names the path actually searched so an operator can- # confirm it in one look instead of guessing.- current_app.logger.error(- 'Agent installer %s is missing from this deployment (searched %s). '- 'Fleet enrollment via /api/v1/servers/%s cannot work until it is '- 'restored; see docs/ARCHITECTURE.md.',- filename, script_path, filename- )- return None, (jsonify({- 'error': f'{filename} is not present on this ServerKit panel',- 'detail': (- 'The panel serves this installer from its own filesystem and the '- 'file is missing, so this is a packaging/deployment problem with '- 'this panel rather than a wrong URL. The panel log records the '- 'exact path searched.'- ),- 'searched_path': script_path,- }), 503)-- with open(script_path, 'r', encoding='utf-8') as f:- content = f.read()-- # Replace placeholders with actual values- content = content.replace('https://your-serverkit.com', _get_external_base_url())- content = content.replace('jhd3197/serverkit-agent', AGENT_GITHUB_REPO)- return content, None---@servers_bp.route('/install.sh', methods=['GET'])-def get_install_script_linux():- """- Get the Linux installation script.-- This endpoint serves the bash installation script for installing- the ServerKit agent on Linux systems.-- Usage (download-then-run, not `curl | bash`: a pipeline reports bash's exit- status, so a failed download would exit 0 having installed nothing):- curl -fsSL https://your-server/api/v1/servers/install.sh \\- -o /tmp/serverkit-agent-install.sh \\- && sudo bash /tmp/serverkit-agent-install.sh \\- --token "YOUR_TOKEN" --server "https://your-server"- """- content, error = _load_installer('install.sh')- if error is not None:- return error-- # Inject the agent version the panel already resolved so enrollment does- # not depend on the installer rediscovering it via the GitHub API. Best- # effort: on failure the placeholder stays empty and the script falls- # back to its own GitHub discovery.- release = _get_latest_agent_release()- version = (release or {}).get('version') or ''- if version and all(c.isalnum() or c in '._-' for c in version):- content = content.replace(- 'SERVERKIT_AGENT_VERSION=""',- f'SERVERKIT_AGENT_VERSION="{version}"',- 1- )-- return Response(- content,- mimetype='text/x-shellscript',- headers={- 'Content-Disposition': 'inline; filename="install.sh"',- 'Cache-Control': 'no-cache'- }- )---@servers_bp.route('/install.ps1', methods=['GET'])-def get_install_script_windows():- """- Get the Windows installation script.-- This endpoint serves the PowerShell installation script for installing- the ServerKit agent on Windows systems.-- Usage:- irm https://your-server/api/v1/servers/install.ps1 | iex; \\- Install-ServerKitAgent -Token "YOUR_TOKEN" -Server "https://your-server"- """- content, error = _load_installer('install.ps1')- if error is not None:- return error-- return Response(- content,- mimetype='text/plain',- headers={- 'Content-Disposition': 'inline; filename="install.ps1"',- 'Cache-Control': 'no-cache'- }- )---@servers_bp.route('/install-instructions/<server_id>', methods=['GET'])-@jwt_required()-def get_install_instructions(server_id):- """- Get installation instructions for a specific server.-- Returns installation commands with the correct API endpoint. Registration- tokens are only shown when they are generated, so the UI supplies the token.- """- server = Server.query.get(server_id)- if not server:- raise not_found('server')-- # Check if server has a valid registration token- if not server.registration_token_hash:- return jsonify({- 'error': 'No registration token available',- 'message': 'Generate a new token using the regenerate-token endpoint'- }), 400-- if server.registration_token_expires and server.registration_token_expires < datetime.utcnow():- return jsonify({- 'error': 'Registration token expired',- 'message': 'Generate a new token using the regenerate-token endpoint'- }), 400-- # Get base URL- base_url = _get_external_base_url()- api_url = f"{base_url}/api/v1/servers"-- return jsonify({- 'linux': {- # Download-then-run rather than `curl … | sudo bash`: in a pipeline- # the shell reports bash's exit status, so a failed download exits 0- # and installs nothing without saying so (issue #101).- 'one_liner': (- f'curl -fsSL {api_url}/install.sh -o /tmp/serverkit-agent-install.sh '- f'&& sudo bash /tmp/serverkit-agent-install.sh '- f'--token "YOUR_TOKEN" --server "{base_url}"'- ),- 'manual': [- f'# Download the script',- f'curl -fsSL {api_url}/install.sh -o install.sh',- f'chmod +x install.sh',- f'',- f'# Run installation',- f'sudo ./install.sh --token "YOUR_TOKEN" --server "{base_url}"'- ]- },- 'windows': {- 'one_liner': f'irm {api_url}/install.ps1 | iex; Install-ServerKitAgent -Token "YOUR_TOKEN" -Server "{base_url}"',- 'manual': [- f'# Download the script (run in PowerShell as Administrator)',- f'Invoke-WebRequest -Uri "{api_url}/install.ps1" -OutFile install.ps1',- f'',- f'# Run installation',- f'.\\install.ps1 -Token "YOUR_TOKEN" -Server "{base_url}"'- ]- },- 'note': 'Replace YOUR_TOKEN with the registration token shown in the UI'- })---# ==================== Agent Updates ====================--# Cache for GitHub releases to avoid rate limiting-_releases_cache = {- 'data': None,- 'expires': None-}--# The agent is built and released from its own repo, tagged plain `vX.Y.Z`. It-# used to ship from this monorepo under `agent-v*` tags; when it moved out,-# nothing here followed it, so this lookup searched a repo that has no agent-# releases at all -- /agent/version answered 503 for every agent polling for an-# update, and the served installer downloaded from a 404. Point both at the-# repo that actually publishes the binaries.-AGENT_GITHUB_REPO = os.environ.get('SERVERKIT_AGENT_GITHUB_REPO', 'jhd3197/serverkit-agent')--# Matches vX.Y.Z but not the malformed release tagged just "v" that sits in the-# agent repo's release list -- that one parses to an empty version and builds-# download URLs like .../releases/download/v/serverkit-agent--linux-amd64.tar.gz.-_AGENT_TAG_RE = re.compile(r'^v(\d[^\s]*)$')---def _get_latest_agent_release():- """Fetch latest agent release from GitHub with caching"""- now = datetime.utcnow()-- # Check cache- if _releases_cache['data'] and _releases_cache['expires'] and _releases_cache['expires'] > now:- return _releases_cache['data']-- try:- # Every release in the agent repo is an agent release, but ask for 100- # anyway so a run of pre-release tags cannot hide the newest stable one.- response = requests.get(- f'https://api.github.com/repos/{AGENT_GITHUB_REPO}/releases',- headers={'Accept': 'application/vnd.github.v3+json'},- params={'per_page': 100},- timeout=10- )- response.raise_for_status()- releases = response.json()-- # Find latest agent release- for release in releases:- match = _AGENT_TAG_RE.match(release.get('tag_name', ''))- if match:- version = match.group(1)-- # Build assets map- assets = {}- for asset in release.get('assets', []):- name = asset['name']- if 'linux-amd64' in name:- assets['linux-amd64'] = asset['browser_download_url']- elif 'linux-arm64' in name:- assets['linux-arm64'] = asset['browser_download_url']- elif 'windows-amd64' in name:- assets['windows-amd64'] = asset['browser_download_url']- elif name == 'checksums.txt':- assets['checksums'] = asset['browser_download_url']-- result = {- 'version': version,- 'tag': release['tag_name'],- 'published_at': release['published_at'],- 'release_url': release['html_url'],- 'assets': assets,- 'body': release.get('body', '')- }-- # Cache for 5 minutes- _releases_cache['data'] = result- _releases_cache['expires'] = now + timedelta(minutes=5)-- return result-- return None-- except Exception as e:- current_app.logger.error(f"Failed to fetch GitHub releases: {e}")- # Return cached data if available, even if expired- if _releases_cache['data']:- return _releases_cache['data']- return None---@servers_bp.route('/agent/version', methods=['GET'])-def get_agent_version():- """- Get the latest agent version information.-- This endpoint is called by agents to check for updates.- Returns version info and download URLs for all platforms.- """- release = _get_latest_agent_release()-- if not release:- return jsonify({- 'error': 'Unable to fetch version information',- 'message': 'GitHub API may be unavailable'- }), 503-- # Get base URL for local downloads (fallback)- base_url = request.url_root.rstrip('/')-- return jsonify({- 'version': release['version'],- 'published_at': release['published_at'],- 'release_notes_url': release['release_url'],- 'downloads': {- 'linux-amd64': release['assets'].get('linux-amd64'),- 'linux-arm64': release['assets'].get('linux-arm64'),- 'windows-amd64': release['assets'].get('windows-amd64'),- },- 'checksums_url': release['assets'].get('checksums'),- 'update_available_message': f"A new version of ServerKit Agent is available: v{release['version']}"- })---@servers_bp.route('/agent/version/check', methods=['POST'])-def check_agent_version():- """- Check if an agent needs to be updated.-- Called by agents with their current version to check if an update is needed.-- Request body:- {- "current_version": "1.0.0",- "os": "linux",- "arch": "amd64"- }- """- data = request.get_json() or {}- current_version = data.get('current_version', '0.0.0')- agent_os = data.get('os', 'linux')- agent_arch = data.get('arch', 'amd64')-- release = _get_latest_agent_release()-- if not release:- return jsonify({- 'update_available': False,- 'error': 'Unable to check for updates'- })-- latest_version = release['version']-- # Compare versions (simple string comparison works for semver)- update_available = _compare_versions(current_version, latest_version) < 0-- platform_key = f"{agent_os}-{agent_arch}"- download_url = release['assets'].get(platform_key)-- return jsonify({- 'update_available': update_available,- 'current_version': current_version,- 'latest_version': latest_version,- 'download_url': download_url,- 'checksums_url': release['assets'].get('checksums'),- 'release_notes_url': release['release_url'],- 'published_at': release['published_at']- })---def _compare_versions(v1, v2):- """- Compare two semantic versions.- Returns: -1 if v1 < v2, 0 if v1 == v2, 1 if v1 > v2- """- def parse_version(v):- # Remove leading 'v' if present- v = v.lstrip('v')- # Split by dots and convert to integers- parts = []- for part in v.split('.'):- # Handle pre-release versions like 1.0.0-beta.1- if '-' in part:- num, _ = part.split('-', 1)- parts.append(int(num) if num.isdigit() else 0)- else:- parts.append(int(part) if part.isdigit() else 0)- # Pad to at least 3 parts- while len(parts) < 3:- parts.append(0)- return parts-- try:- p1 = parse_version(v1)- p2 = parse_version(v2)-- for a, b in zip(p1, p2):- if a < b:- return -1- elif a > b:- return 1- return 0- except:- return 0---@servers_bp.route('/agent/download/<os_name>/<arch>', methods=['GET'])-def download_agent(os_name, arch):- """- Redirect to the appropriate agent download.-- This endpoint redirects to the GitHub release asset for the- requested OS and architecture.- """- # Validate inputs- valid_os = ['linux', 'windows', 'darwin']- valid_arch = ['amd64', 'arm64']-- if os_name not in valid_os:- return jsonify({'error': f'Invalid OS. Valid options: {valid_os}'}), 400-- if arch not in valid_arch:- return jsonify({'error': f'Invalid architecture. Valid options: {valid_arch}'}), 400-- release = _get_latest_agent_release()-- if not release:- return jsonify({'error': 'Unable to fetch release information'}), 503-- platform_key = f"{os_name}-{arch}"- download_url = release['assets'].get(platform_key)-- if not download_url:- return jsonify({- 'error': f'No release available for {os_name}-{arch}',- 'available': list(release['assets'].keys())- }), 404-- # Redirect to GitHub release- return redirect(download_url, code=302)---@servers_bp.route('/agent/checksums', methods=['GET'])-def get_agent_checksums():- """- Get SHA256 checksums for agent binaries.-- Returns the checksums.txt content from the latest release.- """- release = _get_latest_agent_release()-- if not release or not release['assets'].get('checksums'):- return jsonify({'error': 'Checksums not available'}), 404-- try:- response = requests.get(release['assets']['checksums'], timeout=10)- response.raise_for_status()-- return Response(- response.text,- mimetype='text/plain',- headers={- 'Content-Disposition': 'inline; filename="checksums.txt"',- 'X-Agent-Version': release['version']- }- )- except Exception as e:- current_app.logger.error(f"Failed to fetch checksums: {e}")- return jsonify({'error': 'Failed to fetch checksums'}), 503---@servers_bp.route('/<server_id>/agent/update', methods=['POST'])-@developer_required-def trigger_agent_update(server_id):- """- Trigger an agent update on a specific server.-- Sends a command to the agent to check for and install updates.-- Developer role required — this replaces the agent binary and restarts the- service across the fleet, so it must not be reachable by read-only viewers- (every other state-changing server route is already @developer_required).- """- server = Server.query.get(server_id)- if not server:- raise not_found('server')-- if not agent_registry.is_agent_connected(server_id):- raise agent_offline()-- # Get latest version info- release = _get_latest_agent_release()- if not release:- return jsonify({- 'success': False,- 'error': 'Unable to fetch latest version'- }), 503-- # Send update command to agent- result = dispatch_agent_command(- server_id=server_id,- action='agent:update',- params={- 'version': release['version'],- 'force': request.get_json().get('force', False) if request.get_json() else False- },- timeout=60.0 # Updates may take a while- )-- return jsonify(result)---# ==================== Agent Fleet Management ====================--@servers_bp.route('/fleet/health', methods=['GET'])-@admin_required-def get_fleet_health():- """Get aggregated health metrics for the agent fleet"""- return jsonify(fleet_service.get_fleet_health())---@servers_bp.route('/fleet/versions', methods=['GET'])-@admin_required-def list_agent_versions():- """List all available agent versions"""- versions = AgentVersion.query.order_by(AgentVersion.version.desc()).all()- return jsonify([v.to_dict() for v in versions])---@servers_bp.route('/fleet/versions', methods=['POST'])-@admin_required-def add_agent_version():- """Add a new available agent version"""- data = request.get_json()-- if not data.get('version'):- raise field_required('Version')-- version = AgentVersion(- version=data['version'],- channel=data.get('channel', 'stable'),- min_panel_version=data.get('min_panel_version'),- max_panel_version=data.get('max_panel_version'),- release_notes=data.get('release_notes'),- assets=data.get('assets', {}),- published_at=datetime.fromisoformat(data['published_at']) if data.get('published_at') else datetime.utcnow()- )-- db.session.add(version)- db.session.commit()-- return jsonify(version.to_dict()), 201---@servers_bp.route('/fleet/upgrade', methods=['POST'])-@admin_required-def upgrade_fleet():- """Trigger upgrade for selected servers or entire fleet"""- data = json_object()- server_ids = data.get('server_ids', [])- version_id = data.get('version_id')- user_id = get_jwt_identity()-- if not server_ids:- # If no IDs provided, upgrade all online servers- servers = Server.query.filter_by(status='online').all()- server_ids = [s.id for s in servers]-- if not server_ids:- return jsonify({'success': True, 'message': 'No online servers to upgrade'})-- result = fleet_service.upgrade_servers(server_ids, version_id, user_id)- return jsonify(result)---@servers_bp.route('/fleet/rollout', methods=['POST'])-@admin_required-def start_staged_rollout():- """Start a staged rollout"""- data = json_object()- group_id = data.get('group_id')- version_id = data.get('version_id')- batch_size = data.get('batch_size', 5)- delay_minutes = data.get('delay_minutes', 10)- strategy = data.get('strategy', 'staged')- server_ids = data.get('server_ids')- user_id = get_jwt_identity()-- if not version_id:- raise field_required('version_id')-- result = fleet_service.staged_rollout(- group_id, version_id, batch_size, delay_minutes,- strategy, user_id, server_ids- )- return jsonify(result)---@servers_bp.route('/fleet/rollouts', methods=['GET'])-@admin_required-def list_rollouts():- """List rollout history"""- status = request.args.get('status')- limit = request.args.get('limit', 20, type=int)- return jsonify(fleet_service.get_rollouts(status, limit))---@servers_bp.route('/fleet/rollouts/<rollout_id>', methods=['GET'])-@admin_required-def get_rollout(rollout_id):- """Get a specific rollout"""- rollout = fleet_service.get_rollout(rollout_id)- if not rollout:- return jsonify({'error': 'Rollout not found'}), 404- return jsonify(rollout)---@servers_bp.route('/fleet/rollouts/<rollout_id>/cancel', methods=['POST'])-@admin_required-def cancel_rollout(rollout_id):- """Cancel an active rollout"""- success = fleet_service.cancel_rollout(rollout_id)- if not success:- return jsonify({'error': 'Cannot cancel rollout (not running or not found)'}), 400- return jsonify({'success': True, 'message': 'Rollout cancelled'})---@servers_bp.route('/fleet/discovery', methods=['POST'])-@admin_required-def start_discovery_scan():- """Start a network scan for new agents"""- duration = request.args.get('duration', 10, type=int)- agents = discovery_service.start_scan(duration)- return jsonify(agents)---@servers_bp.route('/fleet/discovery', methods=['GET'])-@admin_required-def get_discovered_agents():- """Get results of last discovery scan"""- return jsonify(discovery_service.get_discovered_agents())---@servers_bp.route('/fleet/approve/<server_id>', methods=['POST'])-@admin_required-def approve_agent_registration(server_id):- """Approve a pending agent registration"""- user_id = get_jwt_identity()- success = fleet_service.approve_registration(server_id, user_id)-- if not success:- return jsonify({'error': 'Failed to approve registration'}), 400-- return jsonify({'success': True, 'message': 'Registration approved'})---@servers_bp.route('/fleet/reject/<server_id>', methods=['POST'])-@admin_required-def reject_agent_registration(server_id):- """Reject a pending agent registration"""- success = fleet_service.reject_registration(server_id)-- if not success:- return jsonify({'error': 'Failed to reject registration'}), 400-- return jsonify({'success': True, 'message': 'Registration rejected'})---@servers_bp.route('/fleet/commands/queued', methods=['GET'])-@admin_required-def get_queued_commands():- """Get all pending queued commands"""- server_id = request.args.get('server_id')- commands = fleet_service.get_queued_commands(server_id)- return jsonify(commands)---@servers_bp.route('/fleet/commands/<command_id>/retry', methods=['POST'])-@admin_required-def retry_command(command_id):- """Retry a failed command"""- result = fleet_service.retry_command(command_id)- if not result.get('success'):- return jsonify(result), 400- return jsonify(result)---@servers_bp.route('/fleet/diagnostics/<server_id>', methods=['GET'])-@admin_required-def get_server_diagnostics(server_id):- """Get detailed connection diagnostics for a server"""- diagnostics = fleet_service.get_server_diagnostics(server_id)- if 'error' in diagnostics:- return jsonify(diagnostics), 404- return jsonify(diagnostics)---# ==================== Remote Cron Operations ====================-#-# Endpoints under /servers/<id>/cron/ proxy to the agent's cron:*-# command handlers. They mirror the panel-local /api/v1/cron/* surface-# (CronService) but target a remote host. The agent owns validation and-# crontab IO; this layer is just transport.--from app.services.remote_cron_service import RemoteCronService---def _agent_result(result, ok_status=200):- """Translate an agent_registry.send_command result into an HTTP- response: a failure with its status, success unwrapped."""- if not result.get('success'):- return jsonify(result), _agent_failure_status(result)- # Unwrap the agent's data payload so callers see the same shape as- # the local CronService responses.- data = result.get('data')- if isinstance(data, dict):- return jsonify(data), ok_status- return jsonify({'data': data, 'success': True}), ok_status---@servers_bp.route('/<server_id>/cron/status', methods=['GET'])-@jwt_required()-def remote_cron_status(server_id):- user_id = get_jwt_identity()- result = RemoteCronService.status(server_id, user_id=user_id)- return _agent_result(result)---@servers_bp.route('/<server_id>/cron/jobs', methods=['GET'])-@jwt_required()-def remote_cron_list(server_id):- user_id = get_jwt_identity()- result = RemoteCronService.list_jobs(server_id, user_id=user_id)- return _agent_result(result)---@servers_bp.route('/<server_id>/cron/jobs', methods=['POST'])-@developer_required-def remote_cron_add(server_id):- user_id = get_jwt_identity()- data = request.get_json(silent=True) or {}- schedule = (data.get('schedule') or '').strip()- command = (data.get('command') or '').strip()- if not schedule:- raise field_required('schedule')- if not command:- raise field_required('command')-- result = RemoteCronService.add_job(- server_id, schedule, command,- name=data.get('name'),- description=data.get('description'),- user_id=user_id,- )- return _agent_result(result, ok_status=201)---@servers_bp.route('/<server_id>/cron/jobs/<job_id>', methods=['DELETE'])-@developer_required-def remote_cron_remove(server_id, job_id):- user_id = get_jwt_identity()- result = RemoteCronService.remove_job(server_id, job_id, user_id=user_id)- return _agent_result(result)---@servers_bp.route('/<server_id>/cron/jobs/<job_id>/toggle', methods=['POST'])-@developer_required-def remote_cron_toggle(server_id, job_id):- user_id = get_jwt_identity()- data = request.get_json(silent=True) or {}- enabled = bool(data.get('enabled', True))- result = RemoteCronService.toggle_job(server_id, job_id, enabled, user_id=user_id)- return _agent_result(result)---# ==================== Remote Cloudflared Operations ====================-#-# Auth: the user runs `cloudflared tunnel login` once per server.-# That writes ~/.cloudflared/cert.pem (or /etc/cloudflared/cert.pem-# when run as root). The panel never sees a Cloudflare API token —-# every cloudflared:* action just shells out to the binary, which-# uses the cert for auth.-#-# /status surfaces both "binary installed" and "cert present" so the-# UI can show a "log in first" prompt before letting users hit the-# CRUD actions and getting confusing errors.--from app.services.remote_cloudflared_service import RemoteCloudflaredService---@servers_bp.route('/<server_id>/cloudflared/status', methods=['GET'])-@jwt_required()-def remote_cloudflared_status(server_id):- user_id = get_jwt_identity()- result = RemoteCloudflaredService.status(server_id, user_id=user_id)- return _agent_result(result)---@servers_bp.route('/<server_id>/cloudflared/login', methods=['POST'])-@developer_required-def remote_cloudflared_login(server_id):- """Start `cloudflared tunnel login` on the agent. Returns- {job_id, channel}; the panel subscribes to the corresponding- Socket.IO room and renders the auth_url the agent surfaces."""- user_id = get_jwt_identity()- result = RemoteCloudflaredService.login(server_id, user_id=user_id)- return _agent_result(result)---@servers_bp.route('/<server_id>/cloudflared/tunnels', methods=['GET'])-@jwt_required()-def remote_cloudflared_list(server_id):- user_id = get_jwt_identity()- result = RemoteCloudflaredService.list_tunnels(server_id, user_id=user_id)- return _agent_result(result)---@servers_bp.route('/<server_id>/cloudflared/tunnels', methods=['POST'])-@developer_required-def remote_cloudflared_create(server_id):- user_id = get_jwt_identity()- data = request.get_json(silent=True) or {}- name = (data.get('name') or '').strip()- if not name:- raise field_required('name')-- result = RemoteCloudflaredService.create_tunnel(server_id, name, user_id=user_id)- return _agent_result(result, ok_status=201)---@servers_bp.route('/<server_id>/cloudflared/tunnels/<tunnel_ref>/route', methods=['POST'])-@developer_required-def remote_cloudflared_route(server_id, tunnel_ref):- user_id = get_jwt_identity()- data = request.get_json(silent=True) or {}- hostname = (data.get('hostname') or '').strip()- if not hostname:- raise field_required('hostname')-- result = RemoteCloudflaredService.route_tunnel(- server_id, tunnel_ref, hostname, user_id=user_id,- )- return _agent_result(result)---@servers_bp.route('/<server_id>/cloudflared/tunnels/<tunnel_ref>', methods=['DELETE'])-@developer_required-def remote_cloudflared_delete(server_id, tunnel_ref):- user_id = get_jwt_identity()- result = RemoteCloudflaredService.delete_tunnel(server_id, tunnel_ref, user_id=user_id)- return _agent_result(result)---# ==================== Remote Capability Refresh ====================-#-# Lets the panel ask the agent to re-run its capability probe on-# demand — useful after the user installs a runtime, sudoers entry,-# or new package manager and wants new tabs to light up without an-# agent service restart. The agent's response is the freshly merged-# capabilities map; the agent additionally pushes via the persistent-# Capabilities message so all panel listeners stay in sync.--@servers_bp.route('/<server_id>/refresh-capabilities', methods=['POST'])-@developer_required-def remote_refresh_capabilities(server_id):- user_id = get_jwt_identity()- result = dispatch_agent_command(- server_id=server_id, action='agent:recapabilities',- params={}, user_id=user_id, timeout=20.0,- )- return _agent_result(result)---# ==================== Remote Packages ====================-#-# Exposes the agent's packages:* surface for the Packages tab.-# Long-running operations (install/upgrade) return {job_id, channel};-# the frontend subscribes to Socket.IO room-# server_<id>_<channel> for live progress events.--from app.services.remote_packages_service import RemotePackagesService---@servers_bp.route('/<server_id>/packages', methods=['GET'])-@jwt_required()-def remote_packages_list(server_id):- user_id = get_jwt_identity()- result = RemotePackagesService.list_installed(server_id, user_id=user_id)- return _agent_result(result)---@servers_bp.route('/<server_id>/packages/search', methods=['GET'])-@jwt_required()-def remote_packages_search(server_id):- user_id = get_jwt_identity()- query = (request.args.get('q') or '').strip()- if not query:- raise field_required('q')- try:- limit = int(request.args.get('limit', 100))- except (TypeError, ValueError):- limit = 100- result = RemotePackagesService.search(server_id, query, limit=limit, user_id=user_id)- return _agent_result(result)---@servers_bp.route('/<server_id>/packages/info/<name>', methods=['GET'])-@jwt_required()-def remote_packages_info(server_id, name):- user_id = get_jwt_identity()- result = RemotePackagesService.info(server_id, name, user_id=user_id)- return _agent_result(result)---@servers_bp.route('/<server_id>/packages/update-cache', methods=['POST'])-@developer_required-def remote_packages_update_cache(server_id):- user_id = get_jwt_identity()- result = RemotePackagesService.update_cache(server_id, user_id=user_id)- return _agent_result(result)---@servers_bp.route('/<server_id>/packages/install', methods=['POST'])-@developer_required-def remote_packages_install(server_id):- """Streaming install. Body: {names: ['nginx', 'redis-server']}.- Returns {job_id, channel} immediately; the panel subscribes to the- matching Socket.IO room for live install output."""- user_id = get_jwt_identity()- data = request.get_json(silent=True) or {}- names = data.get('names') or []- if isinstance(names, str):- names = [names]- if not names:- raise field_required('names')- result = RemotePackagesService.install_async(server_id, names, user_id=user_id)- return _agent_result(result)---@servers_bp.route('/<server_id>/packages/remove', methods=['POST'])-@developer_required-def remote_packages_remove(server_id):- user_id = get_jwt_identity()- data = request.get_json(silent=True) or {}- name = (data.get('name') or '').strip()- if not name:- raise field_required('name')- result = RemotePackagesService.remove(server_id, name, user_id=user_id)- return _agent_result(result)---@servers_bp.route('/<server_id>/packages/upgrade', methods=['POST'])-@developer_required-def remote_packages_upgrade(server_id):- """Streaming upgrade. Body: {all: bool, names?: [...]}. Returns- {job_id, channel}."""- user_id = get_jwt_identity()- data = request.get_json(silent=True) or {}- names = data.get('names') or []- all_pkgs = bool(data.get('all', False))- if not all_pkgs and not names:- return jsonify({'error': 'either all=true or names=[...] required'}), 400- result = RemotePackagesService.upgrade(- server_id,- names=names if names else None,- all_packages=all_pkgs,- user_id=user_id,- )- return _agent_result(result)---# ==================== Remote Services (systemd) ====================--from app.services.remote_systemd_service import RemoteSystemdService---@servers_bp.route('/<server_id>/services', methods=['GET'])-@jwt_required()-def remote_services_list(server_id):- user_id = get_jwt_identity()- state = request.args.get('state')- type_ = request.args.get('type', 'service')- result = RemoteSystemdService.list_units(server_id, state=state, type_=type_, user_id=user_id)- return _agent_result(result)---# Static-suffix routes must come before the generic <unit>/<action>-# route so Werkzeug picks the right matcher in registration order.--@servers_bp.route('/<server_id>/services/daemon-reload', methods=['POST'])-@developer_required-def remote_services_daemon_reload(server_id):- user_id = get_jwt_identity()- result = RemoteSystemdService.daemon_reload(server_id, user_id=user_id)- return _agent_result(result)---@servers_bp.route('/<server_id>/services/<unit>/logs', methods=['GET'])-@jwt_required()-def remote_services_logs(server_id, unit):- user_id = get_jwt_identity()- try:- lines = int(request.args.get('lines', 200))- except (TypeError, ValueError):- lines = 200- result = RemoteSystemdService.logs(server_id, unit, lines=lines, user_id=user_id)- return _agent_result(result)---@servers_bp.route('/<server_id>/services/<unit>', methods=['GET'])-@jwt_required()-def remote_services_status(server_id, unit):- user_id = get_jwt_identity()- result = RemoteSystemdService.status(server_id, unit, user_id=user_id)- return _agent_result(result)---@servers_bp.route('/<server_id>/services/<unit>/<action>', methods=['POST'])-@developer_required-def remote_services_control(server_id, unit, action):- user_id = get_jwt_identity()- result = RemoteSystemdService.control(server_id, unit, action, user_id=user_id)- return _agent_result(result)---# ==================== Remote Runtimes (pyenv) ====================-#-# Manages Python versions via pyenv (Linux) and pyenv-win (Windows).-# Bootstrap and install return {job_id, channel} for streaming-# progress; everything else is a synchronous round-trip.--from app.services.remote_runtimes_service import RemoteRuntimesService---@servers_bp.route('/<server_id>/runtimes', methods=['GET'])-@jwt_required()-def remote_runtimes_list(server_id):- user_id = get_jwt_identity()- result = RemoteRuntimesService.list_state(server_id, user_id=user_id)- return _agent_result(result)---@servers_bp.route('/<server_id>/runtimes/pyenv/bootstrap', methods=['POST'])-@developer_required-def remote_runtimes_pyenv_bootstrap(server_id):- user_id = get_jwt_identity()- result = RemoteRuntimesService.pyenv_bootstrap(server_id, user_id=user_id)- return _agent_result(result)---@servers_bp.route('/<server_id>/runtimes/python', methods=['GET'])-@jwt_required()-def remote_runtimes_python_installed(server_id):- user_id = get_jwt_identity()- result = RemoteRuntimesService.python_installed(server_id, user_id=user_id)- return _agent_result(result)---@servers_bp.route('/<server_id>/runtimes/python/available', methods=['GET'])-@jwt_required()-def remote_runtimes_python_available(server_id):- user_id = get_jwt_identity()- result = RemoteRuntimesService.python_available(server_id, user_id=user_id)- return _agent_result(result)---@servers_bp.route('/<server_id>/runtimes/python/current', methods=['GET'])-@jwt_required()-def remote_runtimes_python_current(server_id):- user_id = get_jwt_identity()- result = RemoteRuntimesService.python_current(server_id, user_id=user_id)- return _agent_result(result)---@servers_bp.route('/<server_id>/runtimes/python/install', methods=['POST'])-@developer_required-def remote_runtimes_python_install(server_id):- user_id = get_jwt_identity()- data = request.get_json(silent=True) or {}- version = (data.get('version') or '').strip()- if not version:- raise field_required('version')- result = RemoteRuntimesService.python_install(server_id, version, user_id=user_id)- return _agent_result(result)---@servers_bp.route('/<server_id>/runtimes/python/uninstall', methods=['POST'])-@developer_required-def remote_runtimes_python_uninstall(server_id):- user_id = get_jwt_identity()- data = request.get_json(silent=True) or {}- version = (data.get('version') or '').strip()- if not version:- raise field_required('version')- result = RemoteRuntimesService.python_uninstall(server_id, version, user_id=user_id)- return _agent_result(result)---@servers_bp.route('/<server_id>/runtimes/python/global', methods=['POST'])-@developer_required-def remote_runtimes_python_set_global(server_id):- user_id = get_jwt_identity()- data = request.get_json(silent=True) or {}- version = (data.get('version') or '').strip()- if not version:- raise field_required('version')- result = RemoteRuntimesService.python_set_global(server_id, version, user_id=user_id)- return _agent_result(result)---@servers_bp.route('/<server_id>/runtimes/python/local', methods=['POST'])-@developer_required-def remote_runtimes_python_set_local(server_id):- user_id = get_jwt_identity()- data = request.get_json(silent=True) or {}- version = (data.get('version') or '').strip()- dir_path = (data.get('dir') or '').strip()- if not version or not dir_path:- return jsonify({'error': 'version and dir are required'}), 400- result = RemoteRuntimesService.python_set_local(server_id, version, dir_path, user_id=user_id)- return _agent_result(result)---# ==================== Remote File Operations ====================-#-# Endpoints under /servers/<id>/files/ proxy to the agent's file:*-# command handlers. Phase 3b ships browse/read/write only — the broader-# verb set (delete, mkdir, rename, copy, chmod, search, disk_usage)-# requires new agent handlers and lands in a follow-up. The agent owns-# allowed_paths enforcement; the panel just transports.--from app.services.remote_file_service import RemoteFileService---@servers_bp.route('/<server_id>/files/allowed-paths', methods=['GET'])-@jwt_required()-def remote_file_allowed_paths(server_id):- """Return the file roots the agent advertised on connect. Lets the- file manager seed the browse picker without guessing or hardcoding."""- paths = RemoteFileService.get_allowed_paths(server_id)- return jsonify({'allowed_paths': paths})---@servers_bp.route('/<server_id>/files/browse', methods=['GET'])-@jwt_required()-def remote_file_browse(server_id):- user_id = get_jwt_identity()- path = request.args.get('path')- if not path:- raise field_required('path')- result = RemoteFileService.list_directory(server_id, path, user_id=user_id)- return _agent_result(result)---@servers_bp.route('/<server_id>/files/read', methods=['GET'])-@jwt_required()-def remote_file_read(server_id):- user_id = get_jwt_identity()- path = request.args.get('path')- if not path:- raise field_required('path')- result = RemoteFileService.read_file(server_id, path, user_id=user_id)- return _agent_result(result)---@servers_bp.route('/<server_id>/files/write', methods=['POST'])-@developer_required-def remote_file_write(server_id):- user_id = get_jwt_identity()- data = request.get_json(silent=True) or {}- path = (data.get('path') or '').strip()- content = data.get('content')- if not path:- raise field_required('path')- if content is None:- raise field_required('content')- result = RemoteFileService.write_file(server_id, path, content, user_id=user_id)- return _agent_result(result)+# Area modules register their routes on servers_bp when imported.+from app.api import servers_agents, servers_docker, servers_remote # noqa: E402,F401diff --git a/backend/app/api/servers_agents.py b/backend/app/api/servers_agents.pynew file mode 100644index 00000000..3686c603--- /dev/null+++ b/backend/app/api/servers_agents.py@@ -0,0 +1,706 @@+"""Agent install scripts, agent updates and fleet rollout routes.++Registered on the shared ``servers_bp`` blueprint (see app.api.servers)."""+import os+import re+import requests+from app.models.server import AgentVersion, Server+from flask import Response, current_app, jsonify, redirect, request+from app.middleware.rbac import admin_required, developer_required+from app.exceptions import agent_offline, field_required, not_found+from app.services.agent_registry import agent_registry+from datetime import datetime, timedelta+from app import db+from app.services.discovery_service import discovery_service+from app.services.remote_command_dispatcher import dispatch_agent_command+from app.services.agent_fleet_service import fleet_service+from flask_jwt_extended import get_jwt_identity, jwt_required+from app.api._request import json_object+from app.api.servers import _get_external_base_url, servers_bp+++# ==================== Installation Scripts ====================++def _get_scripts_dir():+ """Resolve the directory holding the fleet-agent installer scripts.++ Every shipped layout has to land on a real directory here:++ * git checkout / release tarball -> ``<tree root>/scripts``+ * Docker image -> ``/app/scripts``, which exists only+ because the Dockerfile explicitly copies the two installers there.++ ``SERVERKIT_SCRIPTS_DIR`` overrides the guess for layouts that split the+ backend away from the rest of the tree.+ """+ override = os.environ.get('SERVERKIT_SCRIPTS_DIR')+ if override:+ return override+ # Go up from backend/app/api to backend, then to scripts+ base_dir = os.path.dirname(os.path.dirname(os.path.dirname(os.path.dirname(__file__))))+ return os.path.join(base_dir, 'scripts')+++def _load_installer(filename):+ """Read an agent installer off disk and stamp this panel's coordinates in.++ Returns ``(content, None)`` on success or ``(None, error_response)`` when the+ file is absent, so the two endpoints below cannot drift apart.+ """+ script_path = os.path.join(_get_scripts_dir(), filename)++ if not os.path.exists(script_path):+ # A missing installer is a packaging fault on THIS panel, never a bad+ # request. The old 404 asserted "no such URL", which is exactly what sent+ # issue #101's reporter hunting for a wrong path -- they filed it as+ # "incorrect paths in setup" -- when the file had simply never been+ # shipped into the image. 503 says "this server is broken, not your URL",+ # and the log line names the path actually searched so an operator can+ # confirm it in one look instead of guessing.+ current_app.logger.error(+ 'Agent installer %s is missing from this deployment (searched %s). '+ 'Fleet enrollment via /api/v1/servers/%s cannot work until it is '+ 'restored; see docs/ARCHITECTURE.md.',+ filename, script_path, filename+ )+ return None, (jsonify({+ 'error': f'{filename} is not present on this ServerKit panel',+ 'detail': (+ 'The panel serves this installer from its own filesystem and the '+ 'file is missing, so this is a packaging/deployment problem with '+ 'this panel rather than a wrong URL. The panel log records the '+ 'exact path searched.'+ ),+ 'searched_path': script_path,+ }), 503)++ with open(script_path, 'r', encoding='utf-8') as f:+ content = f.read()++ # Replace placeholders with actual values+ content = content.replace('https://your-serverkit.com', _get_external_base_url())+ content = content.replace('jhd3197/serverkit-agent', AGENT_GITHUB_REPO)+ return content, None+++@servers_bp.route('/install.sh', methods=['GET'])+def get_install_script_linux():+ """+ Get the Linux installation script.++ This endpoint serves the bash installation script for installing+ the ServerKit agent on Linux systems.++ Usage (download-then-run, not `curl | bash`: a pipeline reports bash's exit+ status, so a failed download would exit 0 having installed nothing):+ curl -fsSL https://your-server/api/v1/servers/install.sh \\+ -o /tmp/serverkit-agent-install.sh \\+ && sudo bash /tmp/serverkit-agent-install.sh \\+ --token "YOUR_TOKEN" --server "https://your-server"+ """+ content, error = _load_installer('install.sh')+ if error is not None:+ return error++ # Inject the agent version the panel already resolved so enrollment does+ # not depend on the installer rediscovering it via the GitHub API. Best+ # effort: on failure the placeholder stays empty and the script falls+ # back to its own GitHub discovery.+ release = _get_latest_agent_release()+ version = (release or {}).get('version') or ''+ if version and all(c.isalnum() or c in '._-' for c in version):+ content = content.replace(+ 'SERVERKIT_AGENT_VERSION=""',+ f'SERVERKIT_AGENT_VERSION="{version}"',+ 1+ )++ return Response(+ content,+ mimetype='text/x-shellscript',+ headers={+ 'Content-Disposition': 'inline; filename="install.sh"',+ 'Cache-Control': 'no-cache'+ }+ )+++@servers_bp.route('/install.ps1', methods=['GET'])+def get_install_script_windows():+ """+ Get the Windows installation script.++ This endpoint serves the PowerShell installation script for installing+ the ServerKit agent on Windows systems.++ Usage:+ irm https://your-server/api/v1/servers/install.ps1 | iex; \\+ Install-ServerKitAgent -Token "YOUR_TOKEN" -Server "https://your-server"+ """+ content, error = _load_installer('install.ps1')+ if error is not None:+ return error++ return Response(+ content,+ mimetype='text/plain',+ headers={+ 'Content-Disposition': 'inline; filename="install.ps1"',+ 'Cache-Control': 'no-cache'+ }+ )+++@servers_bp.route('/install-instructions/<server_id>', methods=['GET'])+@jwt_required()+def get_install_instructions(server_id):+ """+ Get installation instructions for a specific server.++ Returns installation commands with the correct API endpoint. Registration+ tokens are only shown when they are generated, so the UI supplies the token.+ """+ server = Server.query.get(server_id)+ if not server:+ raise not_found('server')++ # Check if server has a valid registration token+ if not server.registration_token_hash:+ return jsonify({+ 'error': 'No registration token available',+ 'message': 'Generate a new token using the regenerate-token endpoint'+ }), 400++ if server.registration_token_expires and server.registration_token_expires < datetime.utcnow():+ return jsonify({+ 'error': 'Registration token expired',+ 'message': 'Generate a new token using the regenerate-token endpoint'+ }), 400++ # Get base URL+ base_url = _get_external_base_url()+ api_url = f"{base_url}/api/v1/servers"++ return jsonify({+ 'linux': {+ # Download-then-run rather than `curl … | sudo bash`: in a pipeline+ # the shell reports bash's exit status, so a failed download exits 0+ # and installs nothing without saying so (issue #101).+ 'one_liner': (+ f'curl -fsSL {api_url}/install.sh -o /tmp/serverkit-agent-install.sh '+ f'&& sudo bash /tmp/serverkit-agent-install.sh '+ f'--token "YOUR_TOKEN" --server "{base_url}"'+ ),+ 'manual': [+ f'# Download the script',+ f'curl -fsSL {api_url}/install.sh -o install.sh',+ f'chmod +x install.sh',+ f'',+ f'# Run installation',+ f'sudo ./install.sh --token "YOUR_TOKEN" --server "{base_url}"'+ ]+ },+ 'windows': {+ 'one_liner': f'irm {api_url}/install.ps1 | iex; Install-ServerKitAgent -Token "YOUR_TOKEN" -Server "{base_url}"',+ 'manual': [+ f'# Download the script (run in PowerShell as Administrator)',+ f'Invoke-WebRequest -Uri "{api_url}/install.ps1" -OutFile install.ps1',+ f'',+ f'# Run installation',+ f'.\\install.ps1 -Token "YOUR_TOKEN" -Server "{base_url}"'+ ]+ },+ 'note': 'Replace YOUR_TOKEN with the registration token shown in the UI'+ })+++# ==================== Agent Updates ====================++# Cache for GitHub releases to avoid rate limiting+_releases_cache = {+ 'data': None,+ 'expires': None+}++# The agent is built and released from its own repo, tagged plain `vX.Y.Z`. It+# used to ship from this monorepo under `agent-v*` tags; when it moved out,+# nothing here followed it, so this lookup searched a repo that has no agent+# releases at all -- /agent/version answered 503 for every agent polling for an+# update, and the served installer downloaded from a 404. Point both at the+# repo that actually publishes the binaries.+AGENT_GITHUB_REPO = os.environ.get('SERVERKIT_AGENT_GITHUB_REPO', 'jhd3197/serverkit-agent')++# Matches vX.Y.Z but not the malformed release tagged just "v" that sits in the+# agent repo's release list -- that one parses to an empty version and builds+# download URLs like .../releases/download/v/serverkit-agent--linux-amd64.tar.gz.+_AGENT_TAG_RE = re.compile(r'^v(\d[^\s]*)$')+++def _get_latest_agent_release():+ """Fetch latest agent release from GitHub with caching"""+ now = datetime.utcnow()++ # Check cache+ if _releases_cache['data'] and _releases_cache['expires'] and _releases_cache['expires'] > now:+ return _releases_cache['data']++ try:+ # Every release in the agent repo is an agent release, but ask for 100+ # anyway so a run of pre-release tags cannot hide the newest stable one.+ response = requests.get(+ f'https://api.github.com/repos/{AGENT_GITHUB_REPO}/releases',+ headers={'Accept': 'application/vnd.github.v3+json'},+ params={'per_page': 100},+ timeout=10+ )+ response.raise_for_status()+ releases = response.json()++ # Find latest agent release+ for release in releases:+ match = _AGENT_TAG_RE.match(release.get('tag_name', ''))+ if match:+ version = match.group(1)++ # Build assets map+ assets = {}+ for asset in release.get('assets', []):+ name = asset['name']+ if 'linux-amd64' in name:+ assets['linux-amd64'] = asset['browser_download_url']+ elif 'linux-arm64' in name:+ assets['linux-arm64'] = asset['browser_download_url']+ elif 'windows-amd64' in name:+ assets['windows-amd64'] = asset['browser_download_url']+ elif name == 'checksums.txt':+ assets['checksums'] = asset['browser_download_url']++ result = {+ 'version': version,+ 'tag': release['tag_name'],+ 'published_at': release['published_at'],+ 'release_url': release['html_url'],+ 'assets': assets,+ 'body': release.get('body', '')+ }++ # Cache for 5 minutes+ _releases_cache['data'] = result+ _releases_cache['expires'] = now + timedelta(minutes=5)++ return result++ return None++ except Exception as e:+ current_app.logger.error(f"Failed to fetch GitHub releases: {e}")+ # Return cached data if available, even if expired+ if _releases_cache['data']:+ return _releases_cache['data']+ return None+++@servers_bp.route('/agent/version', methods=['GET'])+def get_agent_version():+ """+ Get the latest agent version information.++ This endpoint is called by agents to check for updates.+ Returns version info and download URLs for all platforms.+ """+ release = _get_latest_agent_release()++ if not release:+ return jsonify({+ 'error': 'Unable to fetch version information',+ 'message': 'GitHub API may be unavailable'+ }), 503++ # Get base URL for local downloads (fallback)+ base_url = request.url_root.rstrip('/')++ return jsonify({+ 'version': release['version'],+ 'published_at': release['published_at'],+ 'release_notes_url': release['release_url'],+ 'downloads': {+ 'linux-amd64': release['assets'].get('linux-amd64'),+ 'linux-arm64': release['assets'].get('linux-arm64'),+ 'windows-amd64': release['assets'].get('windows-amd64'),+ },+ 'checksums_url': release['assets'].get('checksums'),+ 'update_available_message': f"A new version of ServerKit Agent is available: v{release['version']}"+ })+++@servers_bp.route('/agent/version/check', methods=['POST'])+def check_agent_version():+ """+ Check if an agent needs to be updated.++ Called by agents with their current version to check if an update is needed.++ Request body:+ {+ "current_version": "1.0.0",+ "os": "linux",+ "arch": "amd64"+ }+ """+ data = request.get_json() or {}+ current_version = data.get('current_version', '0.0.0')+ agent_os = data.get('os', 'linux')+ agent_arch = data.get('arch', 'amd64')++ release = _get_latest_agent_release()++ if not release:+ return jsonify({+ 'update_available': False,+ 'error': 'Unable to check for updates'+ })++ latest_version = release['version']++ # Compare versions (simple string comparison works for semver)+ update_available = _compare_versions(current_version, latest_version) < 0++ platform_key = f"{agent_os}-{agent_arch}"+ download_url = release['assets'].get(platform_key)++ return jsonify({+ 'update_available': update_available,+ 'current_version': current_version,+ 'latest_version': latest_version,+ 'download_url': download_url,+ 'checksums_url': release['assets'].get('checksums'),+ 'release_notes_url': release['release_url'],+ 'published_at': release['published_at']+ })+++def _compare_versions(v1, v2):+ """+ Compare two semantic versions.+ Returns: -1 if v1 < v2, 0 if v1 == v2, 1 if v1 > v2+ """+ def parse_version(v):+ # Remove leading 'v' if present+ v = v.lstrip('v')+ # Split by dots and convert to integers+ parts = []+ for part in v.split('.'):+ # Handle pre-release versions like 1.0.0-beta.1+ if '-' in part:+ num, _ = part.split('-', 1)+ parts.append(int(num) if num.isdigit() else 0)+ else:+ parts.append(int(part) if part.isdigit() else 0)+ # Pad to at least 3 parts+ while len(parts) < 3:+ parts.append(0)+ return parts++ try:+ p1 = parse_version(v1)+ p2 = parse_version(v2)++ for a, b in zip(p1, p2):+ if a < b:+ return -1+ elif a > b:+ return 1+ return 0+ except:+ return 0+++@servers_bp.route('/agent/download/<os_name>/<arch>', methods=['GET'])+def download_agent(os_name, arch):+ """+ Redirect to the appropriate agent download.++ This endpoint redirects to the GitHub release asset for the+ requested OS and architecture.+ """+ # Validate inputs+ valid_os = ['linux', 'windows', 'darwin']+ valid_arch = ['amd64', 'arm64']++ if os_name not in valid_os:+ return jsonify({'error': f'Invalid OS. Valid options: {valid_os}'}), 400++ if arch not in valid_arch:+ return jsonify({'error': f'Invalid architecture. Valid options: {valid_arch}'}), 400++ release = _get_latest_agent_release()++ if not release:+ return jsonify({'error': 'Unable to fetch release information'}), 503++ platform_key = f"{os_name}-{arch}"+ download_url = release['assets'].get(platform_key)++ if not download_url:+ return jsonify({+ 'error': f'No release available for {os_name}-{arch}',+ 'available': list(release['assets'].keys())+ }), 404++ # Redirect to GitHub release+ return redirect(download_url, code=302)+++@servers_bp.route('/agent/checksums', methods=['GET'])+def get_agent_checksums():+ """+ Get SHA256 checksums for agent binaries.++ Returns the checksums.txt content from the latest release.+ """+ release = _get_latest_agent_release()++ if not release or not release['assets'].get('checksums'):+ return jsonify({'error': 'Checksums not available'}), 404++ try:+ response = requests.get(release['assets']['checksums'], timeout=10)+ response.raise_for_status()++ return Response(+ response.text,+ mimetype='text/plain',+ headers={+ 'Content-Disposition': 'inline; filename="checksums.txt"',+ 'X-Agent-Version': release['version']+ }+ )+ except Exception as e:+ current_app.logger.error(f"Failed to fetch checksums: {e}")+ return jsonify({'error': 'Failed to fetch checksums'}), 503+++@servers_bp.route('/<server_id>/agent/update', methods=['POST'])+@developer_required+def trigger_agent_update(server_id):+ """+ Trigger an agent update on a specific server.++ Sends a command to the agent to check for and install updates.++ Developer role required — this replaces the agent binary and restarts the+ service across the fleet, so it must not be reachable by read-only viewers+ (every other state-changing server route is already @developer_required).+ """+ server = Server.query.get(server_id)+ if not server:+ raise not_found('server')++ if not agent_registry.is_agent_connected(server_id):+ raise agent_offline()++ # Get latest version info+ release = _get_latest_agent_release()+ if not release:+ return jsonify({+ 'success': False,+ 'error': 'Unable to fetch latest version'+ }), 503++ # Send update command to agent+ result = dispatch_agent_command(+ server_id=server_id,+ action='agent:update',+ params={+ 'version': release['version'],+ 'force': request.get_json().get('force', False) if request.get_json() else False+ },+ timeout=60.0 # Updates may take a while+ )++ return jsonify(result)+++# ==================== Agent Fleet Management ====================++@servers_bp.route('/fleet/health', methods=['GET'])+@admin_required+def get_fleet_health():+ """Get aggregated health metrics for the agent fleet"""+ return jsonify(fleet_service.get_fleet_health())+++@servers_bp.route('/fleet/versions', methods=['GET'])+@admin_required+def list_agent_versions():+ """List all available agent versions"""+ versions = AgentVersion.query.order_by(AgentVersion.version.desc()).all()+ return jsonify([v.to_dict() for v in versions])+++@servers_bp.route('/fleet/versions', methods=['POST'])+@admin_required+def add_agent_version():+ """Add a new available agent version"""+ data = request.get_json()++ if not data.get('version'):+ raise field_required('Version')++ version = AgentVersion(+ version=data['version'],+ channel=data.get('channel', 'stable'),+ min_panel_version=data.get('min_panel_version'),+ max_panel_version=data.get('max_panel_version'),+ release_notes=data.get('release_notes'),+ assets=data.get('assets', {}),+ published_at=datetime.fromisoformat(data['published_at']) if data.get('published_at') else datetime.utcnow()+ )++ db.session.add(version)+ db.session.commit()++ return jsonify(version.to_dict()), 201+++@servers_bp.route('/fleet/upgrade', methods=['POST'])+@admin_required+def upgrade_fleet():+ """Trigger upgrade for selected servers or entire fleet"""+ data = json_object()+ server_ids = data.get('server_ids', [])+ version_id = data.get('version_id')+ user_id = get_jwt_identity()++ if not server_ids:+ # If no IDs provided, upgrade all online servers+ servers = Server.query.filter_by(status='online').all()+ server_ids = [s.id for s in servers]++ if not server_ids:+ return jsonify({'success': True, 'message': 'No online servers to upgrade'})++ result = fleet_service.upgrade_servers(server_ids, version_id, user_id)+ return jsonify(result)+++@servers_bp.route('/fleet/rollout', methods=['POST'])+@admin_required+def start_staged_rollout():+ """Start a staged rollout"""+ data = json_object()+ group_id = data.get('group_id')+ version_id = data.get('version_id')+ batch_size = data.get('batch_size', 5)+ delay_minutes = data.get('delay_minutes', 10)+ strategy = data.get('strategy', 'staged')+ server_ids = data.get('server_ids')+ user_id = get_jwt_identity()++ if not version_id:+ raise field_required('version_id')++ result = fleet_service.staged_rollout(+ group_id, version_id, batch_size, delay_minutes,+ strategy, user_id, server_ids+ )+ return jsonify(result)+++@servers_bp.route('/fleet/rollouts', methods=['GET'])+@admin_required+def list_rollouts():+ """List rollout history"""+ status = request.args.get('status')+ limit = request.args.get('limit', 20, type=int)+ return jsonify(fleet_service.get_rollouts(status, limit))+++@servers_bp.route('/fleet/rollouts/<rollout_id>', methods=['GET'])+@admin_required+def get_rollout(rollout_id):+ """Get a specific rollout"""+ rollout = fleet_service.get_rollout(rollout_id)+ if not rollout:+ return jsonify({'error': 'Rollout not found'}), 404+ return jsonify(rollout)+++@servers_bp.route('/fleet/rollouts/<rollout_id>/cancel', methods=['POST'])+@admin_required+def cancel_rollout(rollout_id):+ """Cancel an active rollout"""+ success = fleet_service.cancel_rollout(rollout_id)+ if not success:+ return jsonify({'error': 'Cannot cancel rollout (not running or not found)'}), 400+ return jsonify({'success': True, 'message': 'Rollout cancelled'})+++@servers_bp.route('/fleet/discovery', methods=['POST'])+@admin_required+def start_discovery_scan():+ """Start a network scan for new agents"""+ duration = request.args.get('duration', 10, type=int)+ agents = discovery_service.start_scan(duration)+ return jsonify(agents)+++@servers_bp.route('/fleet/discovery', methods=['GET'])+@admin_required+def get_discovered_agents():+ """Get results of last discovery scan"""+ return jsonify(discovery_service.get_discovered_agents())+++@servers_bp.route('/fleet/approve/<server_id>', methods=['POST'])+@admin_required+def approve_agent_registration(server_id):+ """Approve a pending agent registration"""+ user_id = get_jwt_identity()+ success = fleet_service.approve_registration(server_id, user_id)++ if not success:+ return jsonify({'error': 'Failed to approve registration'}), 400++ return jsonify({'success': True, 'message': 'Registration approved'})+++@servers_bp.route('/fleet/reject/<server_id>', methods=['POST'])+@admin_required+def reject_agent_registration(server_id):+ """Reject a pending agent registration"""+ success = fleet_service.reject_registration(server_id)++ if not success:+ return jsonify({'error': 'Failed to reject registration'}), 400++ return jsonify({'success': True, 'message': 'Registration rejected'})+++@servers_bp.route('/fleet/commands/queued', methods=['GET'])+@admin_required+def get_queued_commands():+ """Get all pending queued commands"""+ server_id = request.args.get('server_id')+ commands = fleet_service.get_queued_commands(server_id)+ return jsonify(commands)+++@servers_bp.route('/fleet/commands/<command_id>/retry', methods=['POST'])+@admin_required+def retry_command(command_id):+ """Retry a failed command"""+ result = fleet_service.retry_command(command_id)+ if not result.get('success'):+ return jsonify(result), 400+ return jsonify(result)+++@servers_bp.route('/fleet/diagnostics/<server_id>', methods=['GET'])+@admin_required+def get_server_diagnostics(server_id):+ """Get detailed connection diagnostics for a server"""+ diagnostics = fleet_service.get_server_diagnostics(server_id)+ if 'error' in diagnostics:+ return jsonify(diagnostics), 404+ return jsonify(diagnostics)diff --git a/backend/app/api/servers_docker.py b/backend/app/api/servers_docker.pynew file mode 100644index 00000000..9c207e07--- /dev/null+++ b/backend/app/api/servers_docker.py@@ -0,0 +1,445 @@+"""Remote Docker and Compose routes for a paired server.++Registered on the shared ``servers_bp`` blueprint (see app.api.servers)."""+from app.services.remote_docker_service import RemoteDockerService+from app.middleware.rbac import developer_required+from app.exceptions import field_required+from flask_jwt_extended import get_jwt_identity, jwt_required+from flask import jsonify, request+from app.api.servers import _agent_failure_status, servers_bp+++# ==================== Remote Docker Operations ====================+++@servers_bp.route('/available', methods=['GET'])+@jwt_required()+def get_available_servers():+ """Get list of servers available for Docker operations"""+ servers = RemoteDockerService.get_available_servers()+ return jsonify(servers)+++@servers_bp.route('/<server_id>/docker/containers', methods=['GET'])+@jwt_required()+def list_remote_containers(server_id):+ """List containers on a remote server"""+ all_containers = request.args.get('all', 'false').lower() == 'true'+ user_id = get_jwt_identity()++ result = RemoteDockerService.list_containers(server_id, all=all_containers, user_id=user_id)++ if not result.get('success'):+ return jsonify(result), _agent_failure_status(result)++ return jsonify(result.get('data', []))+++@servers_bp.route('/<server_id>/docker/containers/<container_id>', methods=['GET'])+@jwt_required()+def inspect_remote_container(server_id, container_id):+ """Inspect a container on a remote server"""+ user_id = get_jwt_identity()++ result = RemoteDockerService.inspect_container(server_id, container_id, user_id=user_id)++ if not result.get('success'):+ return jsonify(result), _agent_failure_status(result)++ return jsonify(result.get('data'))+++@servers_bp.route('/<server_id>/docker/containers/<container_id>/start', methods=['POST'])+@developer_required+def start_remote_container(server_id, container_id):+ """Start a container on a remote server"""+ user_id = get_jwt_identity()++ result = RemoteDockerService.start_container(server_id, container_id, user_id=user_id)++ if not result.get('success'):+ return jsonify(result), _agent_failure_status(result)++ return jsonify({'message': 'Container started'})+++@servers_bp.route('/<server_id>/docker/containers/<container_id>/stop', methods=['POST'])+@developer_required+def stop_remote_container(server_id, container_id):+ """Stop a container on a remote server"""+ user_id = get_jwt_identity()+ data = request.get_json() or {}+ timeout = data.get('timeout')++ result = RemoteDockerService.stop_container(server_id, container_id, timeout=timeout, user_id=user_id)++ if not result.get('success'):+ return jsonify(result), _agent_failure_status(result)++ return jsonify({'message': 'Container stopped'})+++@servers_bp.route('/<server_id>/docker/containers/<container_id>/restart', methods=['POST'])+@developer_required+def restart_remote_container(server_id, container_id):+ """Restart a container on a remote server"""+ user_id = get_jwt_identity()+ data = request.get_json() or {}+ timeout = data.get('timeout')++ result = RemoteDockerService.restart_container(server_id, container_id, timeout=timeout, user_id=user_id)++ if not result.get('success'):+ return jsonify(result), _agent_failure_status(result)++ return jsonify({'message': 'Container restarted'})+++@servers_bp.route('/<server_id>/docker/containers/<container_id>', methods=['DELETE'])+@developer_required+def remove_remote_container(server_id, container_id):+ """Remove a container on a remote server"""+ user_id = get_jwt_identity()+ force = request.args.get('force', 'false').lower() == 'true'+ remove_volumes = request.args.get('v', 'false').lower() == 'true'++ result = RemoteDockerService.remove_container(+ server_id, container_id,+ force=force, remove_volumes=remove_volumes,+ user_id=user_id+ )++ if not result.get('success'):+ return jsonify(result), _agent_failure_status(result)++ return jsonify({'message': 'Container removed'})+++@servers_bp.route('/<server_id>/docker/containers/<container_id>/stats', methods=['GET'])+@jwt_required()+def get_remote_container_stats(server_id, container_id):+ """Get container stats from a remote server"""+ user_id = get_jwt_identity()++ result = RemoteDockerService.get_container_stats(server_id, container_id, user_id=user_id)++ if not result.get('success'):+ return jsonify(result), _agent_failure_status(result)++ return jsonify(result.get('data'))+++@servers_bp.route('/<server_id>/docker/containers/<container_id>/logs', methods=['GET'])+@jwt_required()+def get_remote_container_logs(server_id, container_id):+ """+ Get container logs from a remote server.++ Query params:+ tail: Number of lines (default 100, 'all' for all lines)+ since: Show logs since timestamp+ timestamps: Include timestamps (default true)+ """+ user_id = get_jwt_identity()+ tail = request.args.get('tail', '100')+ since = request.args.get('since')+ timestamps = request.args.get('timestamps', 'true').lower() == 'true'++ result = RemoteDockerService.get_container_logs(+ server_id, container_id,+ tail=tail, since=since, timestamps=timestamps,+ user_id=user_id+ )++ if not result.get('success'):+ return jsonify(result), _agent_failure_status(result)++ return jsonify(result.get('data'))+++@servers_bp.route('/<server_id>/docker/images', methods=['GET'])+@jwt_required()+def list_remote_images(server_id):+ """List images on a remote server"""+ user_id = get_jwt_identity()++ result = RemoteDockerService.list_images(server_id, user_id=user_id)++ if not result.get('success'):+ return jsonify(result), _agent_failure_status(result)++ return jsonify(result.get('data', []))+++@servers_bp.route('/<server_id>/docker/images/pull', methods=['POST'])+@developer_required+def pull_remote_image(server_id):+ """Pull an image on a remote server"""+ user_id = get_jwt_identity()+ data = request.get_json()++ if not data or not data.get('image'):+ return jsonify({'error': 'Image name required'}), 400++ result = RemoteDockerService.pull_image(server_id, data['image'], user_id=user_id)++ if not result.get('success'):+ return jsonify(result), _agent_failure_status(result)++ return jsonify(result)+++@servers_bp.route('/<server_id>/docker/images/<image_id>', methods=['DELETE'])+@developer_required+def remove_remote_image(server_id, image_id):+ """Remove an image on a remote server"""+ user_id = get_jwt_identity()+ force = request.args.get('force', 'false').lower() == 'true'++ result = RemoteDockerService.remove_image(server_id, image_id, force=force, user_id=user_id)++ if not result.get('success'):+ return jsonify(result), _agent_failure_status(result)++ return jsonify({'message': 'Image removed'})+++@servers_bp.route('/<server_id>/docker/volumes', methods=['GET'])+@jwt_required()+def list_remote_volumes(server_id):+ """List volumes on a remote server"""+ user_id = get_jwt_identity()++ result = RemoteDockerService.list_volumes(server_id, user_id=user_id)++ if not result.get('success'):+ return jsonify(result), _agent_failure_status(result)++ return jsonify(result.get('data', []))+++@servers_bp.route('/<server_id>/docker/volumes/<volume_name>', methods=['DELETE'])+@developer_required+def remove_remote_volume(server_id, volume_name):+ """Remove a volume on a remote server"""+ user_id = get_jwt_identity()+ force = request.args.get('force', 'false').lower() == 'true'++ result = RemoteDockerService.remove_volume(server_id, volume_name, force=force, user_id=user_id)++ if not result.get('success'):+ return jsonify(result), _agent_failure_status(result)++ return jsonify({'message': 'Volume removed'})+++@servers_bp.route('/<server_id>/docker/networks', methods=['GET'])+@jwt_required()+def list_remote_networks(server_id):+ """List networks on a remote server"""+ user_id = get_jwt_identity()++ result = RemoteDockerService.list_networks(server_id, user_id=user_id)++ if not result.get('success'):+ return jsonify(result), _agent_failure_status(result)++ return jsonify(result.get('data', []))+++@servers_bp.route('/<server_id>/docker/networks/<network_id>', methods=['DELETE'])+@developer_required+def remove_remote_network(server_id, network_id):+ """Remove a network on a remote server"""+ user_id = get_jwt_identity()++ result = RemoteDockerService.remove_network(server_id, network_id, user_id=user_id)++ if not result.get('success'):+ return jsonify(result), _agent_failure_status(result)++ return jsonify({'message': 'Network removed'})+++@servers_bp.route('/<server_id>/system/metrics', methods=['GET'])+@jwt_required()+def get_remote_system_metrics(server_id):+ """Get system metrics from a remote server"""+ user_id = get_jwt_identity()++ result = RemoteDockerService.get_system_metrics(server_id, user_id=user_id)++ if not result.get('success'):+ return jsonify(result), _agent_failure_status(result)++ return jsonify(result.get('data'))+++@servers_bp.route('/<server_id>/system/info', methods=['GET'])+@jwt_required()+def get_remote_system_info(server_id):+ """Get system info from a remote server"""+ user_id = get_jwt_identity()++ result = RemoteDockerService.get_system_info(server_id, user_id=user_id)++ if not result.get('success'):+ return jsonify(result), _agent_failure_status(result)++ return jsonify(result.get('data'))+++# ==================== Remote Docker Compose Operations ====================++@servers_bp.route('/<server_id>/docker/compose/projects', methods=['GET'])+@jwt_required()+def list_remote_compose_projects(server_id):+ """List compose projects on a remote server"""+ user_id = get_jwt_identity()++ result = RemoteDockerService.compose_list(server_id, user_id=user_id)++ if not result.get('success'):+ return jsonify(result), _agent_failure_status(result)++ return jsonify(result.get('data', []))+++@servers_bp.route('/<server_id>/docker/compose/ps', methods=['POST'])+@developer_required+def remote_compose_ps(server_id):+ """List containers for a compose project"""+ user_id = get_jwt_identity()+ data = request.get_json()++ if not data or not data.get('project_path'):+ raise field_required('project_path')++ result = RemoteDockerService.compose_ps(+ server_id,+ data['project_path'],+ user_id=user_id+ )++ if not result.get('success'):+ return jsonify(result), _agent_failure_status(result)++ return jsonify(result.get('data', []))+++@servers_bp.route('/<server_id>/docker/compose/up', methods=['POST'])+@developer_required+def remote_compose_up(server_id):+ """Start a compose project"""+ user_id = get_jwt_identity()+ data = request.get_json()++ if not data or not data.get('project_path'):+ raise field_required('project_path')++ result = RemoteDockerService.compose_up(+ server_id,+ data['project_path'],+ detach=data.get('detach', True),+ build=data.get('build', False),+ user_id=user_id+ )++ if not result.get('success'):+ return jsonify(result), _agent_failure_status(result)++ return jsonify(result)+++@servers_bp.route('/<server_id>/docker/compose/down', methods=['POST'])+@developer_required+def remote_compose_down(server_id):+ """Stop a compose project"""+ user_id = get_jwt_identity()+ data = request.get_json()++ if not data or not data.get('project_path'):+ raise field_required('project_path')++ result = RemoteDockerService.compose_down(+ server_id,+ data['project_path'],+ volumes=data.get('volumes', False),+ remove_orphans=data.get('remove_orphans', True),+ user_id=user_id+ )++ if not result.get('success'):+ return jsonify(result), _agent_failure_status(result)++ return jsonify(result)+++@servers_bp.route('/<server_id>/docker/compose/logs', methods=['POST'])+@developer_required+def remote_compose_logs(server_id):+ """Get logs from a compose project"""+ user_id = get_jwt_identity()+ data = request.get_json()++ if not data or not data.get('project_path'):+ raise field_required('project_path')++ result = RemoteDockerService.compose_logs(+ server_id,+ data['project_path'],+ service=data.get('service'),+ tail=data.get('tail', 100),+ user_id=user_id+ )++ if not result.get('success'):+ return jsonify(result), _agent_failure_status(result)++ return jsonify(result.get('data'))+++@servers_bp.route('/<server_id>/docker/compose/restart', methods=['POST'])+@developer_required+def remote_compose_restart(server_id):+ """Restart a compose project or specific service"""+ user_id = get_jwt_identity()+ data = request.get_json()++ if not data or not data.get('project_path'):+ raise field_required('project_path')++ result = RemoteDockerService.compose_restart(+ server_id,+ data['project_path'],+ service=data.get('service'),+ user_id=user_id+ )++ if not result.get('success'):+ return jsonify(result), _agent_failure_status(result)++ return jsonify(result)+++@servers_bp.route('/<server_id>/docker/compose/pull', methods=['POST'])+@developer_required+def remote_compose_pull(server_id):+ """Pull images for a compose project"""+ user_id = get_jwt_identity()+ data = request.get_json()++ if not data or not data.get('project_path'):+ raise field_required('project_path')++ result = RemoteDockerService.compose_pull(+ server_id,+ data['project_path'],+ service=data.get('service'),+ user_id=user_id+ )++ if not result.get('success'):+ return jsonify(result), _agent_failure_status(result)++ return jsonify(result)diff --git a/backend/app/api/servers_remote.py b/backend/app/api/servers_remote.pynew file mode 100644index 00000000..ca17caf0--- /dev/null+++ b/backend/app/api/servers_remote.py@@ -0,0 +1,602 @@+"""Remote terminal, cron, cloudflared, packages, systemd, runtimes and file routes.++Registered on the shared ``servers_bp`` blueprint (see app.api.servers)."""+from app.services.remote_cloudflared_service import RemoteCloudflaredService+from app.services.remote_cron_service import RemoteCronService+from app.services.remote_file_service import RemoteFileService+from app.services.remote_packages_service import RemotePackagesService+from app.services.remote_runtimes_service import RemoteRuntimesService+from app.services.remote_systemd_service import RemoteSystemdService+from app.services.terminal_service import TerminalService+from app.middleware.rbac import developer_required+from app.services.remote_command_dispatcher import dispatch_agent_command+from app.exceptions import field_required+from flask_jwt_extended import get_jwt_identity, jwt_required+from flask import jsonify, request+from app.api.servers import _agent_failure_status, _get_operable_server, servers_bp+++# ==================== Remote Terminal ====================++@servers_bp.route('/<server_id>/terminal', methods=['POST'])+@developer_required+def create_terminal_session(server_id):+ """Create a new terminal session on a remote server.++ Body:+ cols: Terminal width (default: 80)+ rows: Terminal height (default: 24)+ """+ _get_operable_server(server_id)+ user_id = get_jwt_identity()+ data = request.get_json() or {}++ cols = data.get('cols', 80)+ rows = data.get('rows', 24)++ result = TerminalService.create_session(+ server_id=server_id,+ user_id=user_id,+ cols=cols,+ rows=rows+ )++ if not result.get('success'):+ return jsonify(result), _agent_failure_status(result)++ return jsonify(result)+++@servers_bp.route('/terminal/<session_id>/input', methods=['POST'])+@developer_required+def terminal_input(session_id):+ """Send input to a terminal session.++ Body:+ data: Base64-encoded input data+ """+ user_id = get_jwt_identity()+ data = request.get_json()++ if not data or not data.get('data'):+ raise field_required('data')++ result = TerminalService.send_input(+ session_id=session_id,+ data=data['data'],+ user_id=user_id+ )++ if not result.get('success'):+ return jsonify(result), 400++ return jsonify(result)+++@servers_bp.route('/terminal/<session_id>/resize', methods=['POST'])+@developer_required+def terminal_resize(session_id):+ """Resize a terminal session.++ Body:+ cols: New terminal width+ rows: New terminal height+ """+ user_id = get_jwt_identity()+ data = request.get_json()++ if not data or not data.get('cols') or not data.get('rows'):+ return jsonify({'error': 'cols and rows are required'}), 400++ result = TerminalService.resize_session(+ session_id=session_id,+ cols=data['cols'],+ rows=data['rows'],+ user_id=user_id+ )++ if not result.get('success'):+ return jsonify(result), 400++ return jsonify(result)+++@servers_bp.route('/terminal/<session_id>', methods=['DELETE'])+@developer_required+def close_terminal_session(session_id):+ """Close a terminal session."""+ user_id = get_jwt_identity()++ result = TerminalService.close_session(+ session_id=session_id,+ user_id=user_id+ )++ if not result.get('success'):+ return jsonify(result), 400++ return jsonify(result)+++@servers_bp.route('/terminal/sessions', methods=['GET'])+@jwt_required()+def list_terminal_sessions():+ """List all terminal sessions for the current user."""+ user_id = get_jwt_identity()++ sessions = TerminalService.get_user_sessions(user_id)+ return jsonify({+ 'sessions': sessions,+ 'count': len(sessions)+ })+++# ==================== Remote Cron Operations ====================+#+# Endpoints under /servers/<id>/cron/ proxy to the agent's cron:*+# command handlers. They mirror the panel-local /api/v1/cron/* surface+# (CronService) but target a remote host. The agent owns validation and+# crontab IO; this layer is just transport.+++def _agent_result(result, ok_status=200):+ """Translate an agent_registry.send_command result into an HTTP+ response: a failure with its status, success unwrapped."""+ if not result.get('success'):+ return jsonify(result), _agent_failure_status(result)+ # Unwrap the agent's data payload so callers see the same shape as+ # the local CronService responses.+ data = result.get('data')+ if isinstance(data, dict):+ return jsonify(data), ok_status+ return jsonify({'data': data, 'success': True}), ok_status+++@servers_bp.route('/<server_id>/cron/status', methods=['GET'])+@jwt_required()+def remote_cron_status(server_id):+ user_id = get_jwt_identity()+ result = RemoteCronService.status(server_id, user_id=user_id)+ return _agent_result(result)+++@servers_bp.route('/<server_id>/cron/jobs', methods=['GET'])+@jwt_required()+def remote_cron_list(server_id):+ user_id = get_jwt_identity()+ result = RemoteCronService.list_jobs(server_id, user_id=user_id)+ return _agent_result(result)+++@servers_bp.route('/<server_id>/cron/jobs', methods=['POST'])+@developer_required+def remote_cron_add(server_id):+ user_id = get_jwt_identity()+ data = request.get_json(silent=True) or {}+ schedule = (data.get('schedule') or '').strip()+ command = (data.get('command') or '').strip()+ if not schedule:+ raise field_required('schedule')+ if not command:+ raise field_required('command')++ result = RemoteCronService.add_job(+ server_id, schedule, command,+ name=data.get('name'),+ description=data.get('description'),+ user_id=user_id,+ )+ return _agent_result(result, ok_status=201)+++@servers_bp.route('/<server_id>/cron/jobs/<job_id>', methods=['DELETE'])+@developer_required+def remote_cron_remove(server_id, job_id):+ user_id = get_jwt_identity()+ result = RemoteCronService.remove_job(server_id, job_id, user_id=user_id)+ return _agent_result(result)+++@servers_bp.route('/<server_id>/cron/jobs/<job_id>/toggle', methods=['POST'])+@developer_required+def remote_cron_toggle(server_id, job_id):+ user_id = get_jwt_identity()+ data = request.get_json(silent=True) or {}+ enabled = bool(data.get('enabled', True))+ result = RemoteCronService.toggle_job(server_id, job_id, enabled, user_id=user_id)+ return _agent_result(result)+++# ==================== Remote Cloudflared Operations ====================+#+# Auth: the user runs `cloudflared tunnel login` once per server.+# That writes ~/.cloudflared/cert.pem (or /etc/cloudflared/cert.pem+# when run as root). The panel never sees a Cloudflare API token —+# every cloudflared:* action just shells out to the binary, which+# uses the cert for auth.+#+# /status surfaces both "binary installed" and "cert present" so the+# UI can show a "log in first" prompt before letting users hit the+# CRUD actions and getting confusing errors.+++@servers_bp.route('/<server_id>/cloudflared/status', methods=['GET'])+@jwt_required()+def remote_cloudflared_status(server_id):+ user_id = get_jwt_identity()+ result = RemoteCloudflaredService.status(server_id, user_id=user_id)+ return _agent_result(result)+++@servers_bp.route('/<server_id>/cloudflared/login', methods=['POST'])+@developer_required+def remote_cloudflared_login(server_id):+ """Start `cloudflared tunnel login` on the agent. Returns+ {job_id, channel}; the panel subscribes to the corresponding+ Socket.IO room and renders the auth_url the agent surfaces."""+ user_id = get_jwt_identity()+ result = RemoteCloudflaredService.login(server_id, user_id=user_id)+ return _agent_result(result)+++@servers_bp.route('/<server_id>/cloudflared/tunnels', methods=['GET'])+@jwt_required()+def remote_cloudflared_list(server_id):+ user_id = get_jwt_identity()+ result = RemoteCloudflaredService.list_tunnels(server_id, user_id=user_id)+ return _agent_result(result)+++@servers_bp.route('/<server_id>/cloudflared/tunnels', methods=['POST'])+@developer_required+def remote_cloudflared_create(server_id):+ user_id = get_jwt_identity()+ data = request.get_json(silent=True) or {}+ name = (data.get('name') or '').strip()+ if not name:+ raise field_required('name')++ result = RemoteCloudflaredService.create_tunnel(server_id, name, user_id=user_id)+ return _agent_result(result, ok_status=201)+++@servers_bp.route('/<server_id>/cloudflared/tunnels/<tunnel_ref>/route', methods=['POST'])+@developer_required+def remote_cloudflared_route(server_id, tunnel_ref):+ user_id = get_jwt_identity()+ data = request.get_json(silent=True) or {}+ hostname = (data.get('hostname') or '').strip()+ if not hostname:+ raise field_required('hostname')++ result = RemoteCloudflaredService.route_tunnel(+ server_id, tunnel_ref, hostname, user_id=user_id,+ )+ return _agent_result(result)+++@servers_bp.route('/<server_id>/cloudflared/tunnels/<tunnel_ref>', methods=['DELETE'])+@developer_required+def remote_cloudflared_delete(server_id, tunnel_ref):+ user_id = get_jwt_identity()+ result = RemoteCloudflaredService.delete_tunnel(server_id, tunnel_ref, user_id=user_id)+ return _agent_result(result)+++# ==================== Remote Capability Refresh ====================+#+# Lets the panel ask the agent to re-run its capability probe on+# demand — useful after the user installs a runtime, sudoers entry,+# or new package manager and wants new tabs to light up without an+# agent service restart. The agent's response is the freshly merged+# capabilities map; the agent additionally pushes via the persistent+# Capabilities message so all panel listeners stay in sync.++@servers_bp.route('/<server_id>/refresh-capabilities', methods=['POST'])+@developer_required+def remote_refresh_capabilities(server_id):+ user_id = get_jwt_identity()+ result = dispatch_agent_command(+ server_id=server_id, action='agent:recapabilities',+ params={}, user_id=user_id, timeout=20.0,+ )+ return _agent_result(result)+++# ==================== Remote Packages ====================+#+# Exposes the agent's packages:* surface for the Packages tab.+# Long-running operations (install/upgrade) return {job_id, channel};+# the frontend subscribes to Socket.IO room+# server_<id>_<channel> for live progress events.+++@servers_bp.route('/<server_id>/packages', methods=['GET'])+@jwt_required()+def remote_packages_list(server_id):+ user_id = get_jwt_identity()+ result = RemotePackagesService.list_installed(server_id, user_id=user_id)+ return _agent_result(result)+++@servers_bp.route('/<server_id>/packages/search', methods=['GET'])+@jwt_required()+def remote_packages_search(server_id):+ user_id = get_jwt_identity()+ query = (request.args.get('q') or '').strip()+ if not query:+ raise field_required('q')+ try:+ limit = int(request.args.get('limit', 100))+ except (TypeError, ValueError):+ limit = 100+ result = RemotePackagesService.search(server_id, query, limit=limit, user_id=user_id)+ return _agent_result(result)+++@servers_bp.route('/<server_id>/packages/info/<name>', methods=['GET'])+@jwt_required()+def remote_packages_info(server_id, name):+ user_id = get_jwt_identity()+ result = RemotePackagesService.info(server_id, name, user_id=user_id)+ return _agent_result(result)+++@servers_bp.route('/<server_id>/packages/update-cache', methods=['POST'])+@developer_required+def remote_packages_update_cache(server_id):+ user_id = get_jwt_identity()+ result = RemotePackagesService.update_cache(server_id, user_id=user_id)+ return _agent_result(result)+++@servers_bp.route('/<server_id>/packages/install', methods=['POST'])+@developer_required+def remote_packages_install(server_id):+ """Streaming install. Body: {names: ['nginx', 'redis-server']}.+ Returns {job_id, channel} immediately; the panel subscribes to the+ matching Socket.IO room for live install output."""+ user_id = get_jwt_identity()+ data = request.get_json(silent=True) or {}+ names = data.get('names') or []+ if isinstance(names, str):+ names = [names]+ if not names:+ raise field_required('names')+ result = RemotePackagesService.install_async(server_id, names, user_id=user_id)+ return _agent_result(result)+++@servers_bp.route('/<server_id>/packages/remove', methods=['POST'])+@developer_required+def remote_packages_remove(server_id):+ user_id = get_jwt_identity()+ data = request.get_json(silent=True) or {}+ name = (data.get('name') or '').strip()+ if not name:+ raise field_required('name')+ result = RemotePackagesService.remove(server_id, name, user_id=user_id)+ return _agent_result(result)+++@servers_bp.route('/<server_id>/packages/upgrade', methods=['POST'])+@developer_required+def remote_packages_upgrade(server_id):+ """Streaming upgrade. Body: {all: bool, names?: [...]}. Returns+ {job_id, channel}."""+ user_id = get_jwt_identity()+ data = request.get_json(silent=True) or {}+ names = data.get('names') or []+ all_pkgs = bool(data.get('all', False))+ if not all_pkgs and not names:+ return jsonify({'error': 'either all=true or names=[...] required'}), 400+ result = RemotePackagesService.upgrade(+ server_id,+ names=names if names else None,+ all_packages=all_pkgs,+ user_id=user_id,+ )+ return _agent_result(result)+++# ==================== Remote Services (systemd) ====================+++@servers_bp.route('/<server_id>/services', methods=['GET'])+@jwt_required()+def remote_services_list(server_id):+ user_id = get_jwt_identity()+ state = request.args.get('state')+ type_ = request.args.get('type', 'service')+ result = RemoteSystemdService.list_units(server_id, state=state, type_=type_, user_id=user_id)+ return _agent_result(result)+++# Static-suffix routes must come before the generic <unit>/<action>+# route so Werkzeug picks the right matcher in registration order.++@servers_bp.route('/<server_id>/services/daemon-reload', methods=['POST'])+@developer_required+def remote_services_daemon_reload(server_id):+ user_id = get_jwt_identity()+ result = RemoteSystemdService.daemon_reload(server_id, user_id=user_id)+ return _agent_result(result)+++@servers_bp.route('/<server_id>/services/<unit>/logs', methods=['GET'])+@jwt_required()+def remote_services_logs(server_id, unit):+ user_id = get_jwt_identity()+ try:+ lines = int(request.args.get('lines', 200))+ except (TypeError, ValueError):+ lines = 200+ result = RemoteSystemdService.logs(server_id, unit, lines=lines, user_id=user_id)+ return _agent_result(result)+++@servers_bp.route('/<server_id>/services/<unit>', methods=['GET'])+@jwt_required()+def remote_services_status(server_id, unit):+ user_id = get_jwt_identity()+ result = RemoteSystemdService.status(server_id, unit, user_id=user_id)+ return _agent_result(result)+++@servers_bp.route('/<server_id>/services/<unit>/<action>', methods=['POST'])+@developer_required+def remote_services_control(server_id, unit, action):+ user_id = get_jwt_identity()+ result = RemoteSystemdService.control(server_id, unit, action, user_id=user_id)+ return _agent_result(result)+++# ==================== Remote Runtimes (pyenv) ====================+#+# Manages Python versions via pyenv (Linux) and pyenv-win (Windows).+# Bootstrap and install return {job_id, channel} for streaming+# progress; everything else is a synchronous round-trip.+++@servers_bp.route('/<server_id>/runtimes', methods=['GET'])+@jwt_required()+def remote_runtimes_list(server_id):+ user_id = get_jwt_identity()+ result = RemoteRuntimesService.list_state(server_id, user_id=user_id)+ return _agent_result(result)+++@servers_bp.route('/<server_id>/runtimes/pyenv/bootstrap', methods=['POST'])+@developer_required+def remote_runtimes_pyenv_bootstrap(server_id):+ user_id = get_jwt_identity()+ result = RemoteRuntimesService.pyenv_bootstrap(server_id, user_id=user_id)+ return _agent_result(result)+++@servers_bp.route('/<server_id>/runtimes/python', methods=['GET'])+@jwt_required()+def remote_runtimes_python_installed(server_id):+ user_id = get_jwt_identity()+ result = RemoteRuntimesService.python_installed(server_id, user_id=user_id)+ return _agent_result(result)+++@servers_bp.route('/<server_id>/runtimes/python/available', methods=['GET'])+@jwt_required()+def remote_runtimes_python_available(server_id):+ user_id = get_jwt_identity()+ result = RemoteRuntimesService.python_available(server_id, user_id=user_id)+ return _agent_result(result)+++@servers_bp.route('/<server_id>/runtimes/python/current', methods=['GET'])+@jwt_required()+def remote_runtimes_python_current(server_id):+ user_id = get_jwt_identity()+ result = RemoteRuntimesService.python_current(server_id, user_id=user_id)+ return _agent_result(result)+++@servers_bp.route('/<server_id>/runtimes/python/install', methods=['POST'])+@developer_required+def remote_runtimes_python_install(server_id):+ user_id = get_jwt_identity()+ data = request.get_json(silent=True) or {}+ version = (data.get('version') or '').strip()+ if not version:+ raise field_required('version')+ result = RemoteRuntimesService.python_install(server_id, version, user_id=user_id)+ return _agent_result(result)+++@servers_bp.route('/<server_id>/runtimes/python/uninstall', methods=['POST'])+@developer_required+def remote_runtimes_python_uninstall(server_id):+ user_id = get_jwt_identity()+ data = request.get_json(silent=True) or {}+ version = (data.get('version') or '').strip()+ if not version:+ raise field_required('version')+ result = RemoteRuntimesService.python_uninstall(server_id, version, user_id=user_id)+ return _agent_result(result)+++@servers_bp.route('/<server_id>/runtimes/python/global', methods=['POST'])+@developer_required+def remote_runtimes_python_set_global(server_id):+ user_id = get_jwt_identity()+ data = request.get_json(silent=True) or {}+ version = (data.get('version') or '').strip()+ if not version:+ raise field_required('version')+ result = RemoteRuntimesService.python_set_global(server_id, version, user_id=user_id)+ return _agent_result(result)+++@servers_bp.route('/<server_id>/runtimes/python/local', methods=['POST'])+@developer_required+def remote_runtimes_python_set_local(server_id):+ user_id = get_jwt_identity()+ data = request.get_json(silent=True) or {}+ version = (data.get('version') or '').strip()+ dir_path = (data.get('dir') or '').strip()+ if not version or not dir_path:+ return jsonify({'error': 'version and dir are required'}), 400+ result = RemoteRuntimesService.python_set_local(server_id, version, dir_path, user_id=user_id)+ return _agent_result(result)+++# ==================== Remote File Operations ====================+#+# Endpoints under /servers/<id>/files/ proxy to the agent's file:*+# command handlers. Phase 3b ships browse/read/write only — the broader+# verb set (delete, mkdir, rename, copy, chmod, search, disk_usage)+# requires new agent handlers and lands in a follow-up. The agent owns+# allowed_paths enforcement; the panel just transports.+++@servers_bp.route('/<server_id>/files/allowed-paths', methods=['GET'])+@jwt_required()+def remote_file_allowed_paths(server_id):+ """Return the file roots the agent advertised on connect. Lets the+ file manager seed the browse picker without guessing or hardcoding."""+ paths = RemoteFileService.get_allowed_paths(server_id)+ return jsonify({'allowed_paths': paths})+++@servers_bp.route('/<server_id>/files/browse', methods=['GET'])+@jwt_required()+def remote_file_browse(server_id):+ user_id = get_jwt_identity()+ path = request.args.get('path')+ if not path:+ raise field_required('path')+ result = RemoteFileService.list_directory(server_id, path, user_id=user_id)+ return _agent_result(result)+++@servers_bp.route('/<server_id>/files/read', methods=['GET'])+@jwt_required()+def remote_file_read(server_id):+ user_id = get_jwt_identity()+ path = request.args.get('path')+ if not path:+ raise field_required('path')+ result = RemoteFileService.read_file(server_id, path, user_id=user_id)+ return _agent_result(result)+++@servers_bp.route('/<server_id>/files/write', methods=['POST'])+@developer_required+def remote_file_write(server_id):+ user_id = get_jwt_identity()+ data = request.get_json(silent=True) or {}+ path = (data.get('path') or '').strip()+ content = data.get('content')+ if not path:+ raise field_required('path')+ if content is None:+ raise field_required('content')+ result = RemoteFileService.write_file(server_id, path, content, user_id=user_id)+ return _agent_result(result)diff --git a/backend/tests/api_controller_boundary_baseline.json b/backend/tests/api_controller_boundary_baseline.jsonindex e4465ada..1cc97396 100644--- a/backend/tests/api_controller_boundary_baseline.json+++ b/backend/tests/api_controller_boundary_baseline.json@@ -134,6 +134,10 @@"owner": "ServerKit backend / servers domain","rationale": "Legacy servers controllers still cross a persistence or host-operation boundary; move each call into an app.services use case before removing it."},+ "api/servers_agents.py": {+ "owner": "ServerKit backend / servers agents domain",+ "rationale": "Legacy servers agents controllers still cross a persistence or host-operation boundary; move each call into an app.services use case before removing it."+ },"api/shared_resources.py": {"owner": "ServerKit backend / shared resources domain","rationale": "Legacy shared resources controllers still cross a persistence or host-operation boundary; move each call into an app.services use case before removing it."@@ -553,8 +557,6 @@"api/recipes.py::submit_recipe_handoff::persistence::DeploymentJob.query.get(job_id)::1","api/secrets_webhooks.py::create_vault::persistence::Workspace.query.get(explicit_ws)::1","api/servers.py::acknowledge_alert::persistence::SecurityAlert.query.get(alert_id)::1",- "api/servers.py::add_agent_version::persistence::db.session.add(version)::1",- "api/servers.py::add_agent_version::persistence::db.session.commit()::1","api/servers.py::compare_server_metrics::persistence::Server.query.get(server_id)::1","api/servers.py::compare_server_metrics::persistence::ServerMetrics.query.filter_by(server_id=server_id).order_by(ServerMetrics.timestamp.desc()).limit(limit).all()::1","api/servers.py::create_group::persistence::db.session.add(group)::1",@@ -575,7 +577,6 @@"api/servers.py::get_connection_info::persistence::AgentSession.query.filter_by(server_id=server_id, is_active=True).first()::1","api/servers.py::get_connection_info::persistence::Server.query.get(server_id)::1","api/servers.py::get_group::persistence::ServerGroup.query.get(group_id)::1",- "api/servers.py::get_install_instructions::persistence::Server.query.get(server_id)::1","api/servers.py::get_server::persistence::Server.query.get(server_id)::1","api/servers.py::get_server::persistence::db.session.commit()::1","api/servers.py::get_server::persistence::db.session.rollback()::1",@@ -585,7 +586,6 @@"api/servers.py::get_server_security_alerts::persistence::Server.query.get(server_id)::1","api/servers.py::get_server_status::persistence::Server.query.get(server_id)::1","api/servers.py::get_servers_overview::persistence::Server.query.options(joinedload(Server.group)).all()::1",- "api/servers.py::list_agent_versions::persistence::AgentVersion.query.order_by(AgentVersion.version.desc()).all()::1","api/servers.py::list_groups::persistence::ServerGroup.query.all()::1","api/servers.py::ping_server::persistence::Server.query.get(server_id)::1","api/servers.py::regenerate_token::persistence::db.session.commit()::1",@@ -599,14 +599,18 @@"api/servers.py::set_server_workspace::persistence::Workspace.query.get(target)::1","api/servers.py::set_server_workspace::persistence::db.session.commit()::1","api/servers.py::start_server_onboarding::persistence::Server.query.get(server_id)::1",- "api/servers.py::trigger_agent_update::persistence::Server.query.get(server_id)::1","api/servers.py::update_allowed_ips::persistence::Server.query.get(server_id)::1","api/servers.py::update_allowed_ips::persistence::db.session.commit()::1","api/servers.py::update_group::persistence::ServerGroup.query.get(group_id)::1","api/servers.py::update_group::persistence::db.session.commit()::1","api/servers.py::update_server::persistence::Server.query.get(server_id)::1","api/servers.py::update_server::persistence::db.session.commit()::1",- "api/servers.py::upgrade_fleet::persistence::Server.query.filter_by(status='online').all()::1",+ "api/servers_agents.py::add_agent_version::persistence::db.session.add(version)::1",+ "api/servers_agents.py::add_agent_version::persistence::db.session.commit()::1",+ "api/servers_agents.py::get_install_instructions::persistence::Server.query.get(server_id)::1",+ "api/servers_agents.py::list_agent_versions::persistence::AgentVersion.query.order_by(AgentVersion.version.desc()).all()::1",+ "api/servers_agents.py::trigger_agent_update::persistence::Server.query.get(server_id)::1",+ "api/servers_agents.py::upgrade_fleet::persistence::Server.query.filter_by(status='online').all()::1","api/shared_resources.py::_check_resource_write::persistence::ManagedDatabase.query_active().filter_by(id=int(resource_id)).first()::1","api/shared_resources.py::_check_resource_write::persistence::Server.query.get(str(resource_id))::1","api/shared_resources.py::_resolve_app::persistence::Application.query_active().filter_by(id=rid).first()::1",diff --git a/backend/tests/api_controller_boundary_scan.py b/backend/tests/api_controller_boundary_scan.pyindex de447245..d7fac64f 100644--- a/backend/tests/api_controller_boundary_scan.py+++ b/backend/tests/api_controller_boundary_scan.py@@ -83,9 +83,16 @@ def _import_aliases(tree: ast.Module) -> dict[str, str]:def _is_controller(tree: ast.Module, aliases: dict[str, str]) -> bool:+ """A module that creates a Blueprint or registers routes on one. The+ second half matters: an area module that adds routes to a blueprint+ imported from elsewhere would otherwise escape the scan entirely."""return any(- isinstance(node, ast.Call)- and _dotted_name(node.func, aliases) in {'Blueprint', 'flask.Blueprint'}+ (isinstance(node, ast.Call)+ and _dotted_name(node.func, aliases) in {'Blueprint', 'flask.Blueprint'})+ or (isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)) and any(+ isinstance(dec, ast.Call) and isinstance(dec.func, ast.Attribute)+ and dec.func.attr == 'route'+ for dec in node.decorator_list))for node in ast.walk(tree))diff --git a/backend/tests/test_agent_installer_endpoints.py b/backend/tests/test_agent_installer_endpoints.pyindex 6aedebf9..0373da27 100644--- a/backend/tests/test_agent_installer_endpoints.py+++ b/backend/tests/test_agent_installer_endpoints.py@@ -22,8 +22,8 @@ from unittest.mock import patchimport pytest-from app.api import servers as servers_api-from app.api.servers import _get_scripts_dir+from app.api import servers_agents as servers_api+from app.api.servers_agents import _get_scripts_dirREPO_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))diff --git a/backend/tests/test_remote_agent_failure_status.py b/backend/tests/test_remote_agent_failure_status.pyindex caf90108..6e9c9900 100644--- a/backend/tests/test_remote_agent_failure_status.py+++ b/backend/tests/test_remote_agent_failure_status.py@@ -27,7 +27,7 @@ def ctx(app):def test_failure_status_follows_the_agent_code(client, ctx, code, status, method, path, service_fn):headers, server_id = ctxfailure = {'success': False, 'code': code, 'error': 'nope'}- with patch(f'app.api.servers.RemoteDockerService.{service_fn}', return_value=failure):+ with patch(f'app.services.remote_docker_service.RemoteDockerService.{service_fn}', return_value=failure):resp = getattr(client, method)(f'/api/v1/servers/{server_id}{path}', headers=headers,json={'project_path': '/srv/app'})assert resp.status_code == statusdiff --git a/backend/tests/test_server_workspace_access.py b/backend/tests/test_server_workspace_access.pyindex 9c6e00e3..47321365 100644--- a/backend/tests/test_server_workspace_access.py+++ b/backend/tests/test_server_workspace_access.py@@ -35,7 +35,7 @@ def test_outsider_is_refused(client, setup, method, url, body):body = {k: setup['own_ws'] if v == '{own_ws}' else v for k, v in body.items()}before = Server.query.get(setup['server'])token_hash, ws_id = before.registration_token_hash, before.workspace_id- with patch('app.api.servers.TerminalService.create_session',+ with patch('app.services.terminal_service.TerminalService.create_session',return_value={'success': True}) as create:resp = getattr(client, method)(url.format(sid=setup['server']), json=body,headers=headers_for(setup['outsider']))@@ -48,7 +48,7 @@ def test_outsider_is_refused(client, setup, method, url, body):@pytest.mark.parametrize('who', ['member', 'admin'])def test_member_and_admin_can_open_terminal(client, setup, who):- with patch('app.api.servers.TerminalService.create_session',+ with patch('app.services.terminal_service.TerminalService.create_session',return_value={'success': True, 'session_id': 's1'}) as create:resp = client.post(f"/api/v1/servers/{setup['server']}/terminal", json={},headers=headers_for(setup[who]))@@ -70,7 +70,7 @@ def test_default_workspace_servers_stay_shared(client, setup):from app.services.workspace_service import WorkspaceServiceserver = make_server(db, name='swa-default',workspace_id=WorkspaceService.ensure_default_workspace().id)- with patch('app.api.servers.TerminalService.create_session',+ with patch('app.services.terminal_service.TerminalService.create_session',return_value={'success': True, 'session_id': 's2'}):resp = client.post(f'/api/v1/servers/{server.id}/terminal', json={},headers=headers_for(setup['outsider']))