virtuai-cli 0.1.0__py3-none-any.whl

virtuai_cli/__init__.py

@@ -0,0 +1,2 @@
+"""VirtuAI local CLI."""
+__version__ = "0.1.0"

virtuai_cli/config.py

@@ -0,0 +1,115 @@
+"""Persistent config stored in ~/.virtuai/config.json."""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+from pathlib import Path
+from typing import Any, Optional
+
+
+_CONFIG_DIR = Path.home() / ".virtuai"
+_CONFIG_FILE = _CONFIG_DIR / "config.json"
+_CREDENTIALS_FILE = _CONFIG_DIR / "credentials.json"  # fallback when keyring unavailable
+
+_KEYRING_SERVICE = "virtuai-cli"
+_KEYRING_CLI_TOKEN_KEY = "cli_token"
+_KEYRING_USER_TOKEN_KEY = "user_token"
+
+
+def _ensure_dir() -> None:
+    _CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+
+
+def load() -> dict:
+    if not _CONFIG_FILE.exists():
+        return {}
+    try:
+        return json.loads(_CONFIG_FILE.read_text())
+    except Exception:
+        return {}
+
+
+def save(data: dict) -> None:
+    _ensure_dir()
+    _CONFIG_FILE.write_text(json.dumps(data, indent=2))
+
+
+def get(key: str, default: Any = None) -> Any:
+    return load().get(key, default)
+
+
+def set_key(key: str, value: Any) -> None:
+    data = load()
+    data[key] = value
+    save(data)
+
+
+def get_server_url() -> str:
+    return get("server_url", "https://app.virtuai.io")
+
+
+# ---------------------------------------------------------------------------
+# Token storage — OS keychain with ~/.virtuai/credentials fallback
+# ---------------------------------------------------------------------------
+
+def _keyring_available() -> bool:
+    try:
+        import keyring
+        keyring.get_password(_KEYRING_SERVICE, "test")
+        return True
+    except Exception:
+        return False
+
+
+def store_token(key: str, value: str) -> None:
+    try:
+        import keyring
+        keyring.set_password(_KEYRING_SERVICE, key, value)
+        return
+    except Exception:
+        pass
+    # Fallback: encrypted-ish plaintext with strict permissions
+    _ensure_dir()
+    creds: dict = {}
+    if _CREDENTIALS_FILE.exists():
+        try:
+            creds = json.loads(_CREDENTIALS_FILE.read_text())
+        except Exception:
+            pass
+    creds[key] = value
+    _CREDENTIALS_FILE.write_text(json.dumps(creds))
+    _CREDENTIALS_FILE.chmod(stat.S_IRUSR | stat.S_IWUSR)
+
+
+def load_token(key: str) -> Optional[str]:
+    try:
+        import keyring
+        val = keyring.get_password(_KEYRING_SERVICE, key)
+        if val:
+            return val
+    except Exception:
+        pass
+    if _CREDENTIALS_FILE.exists():
+        try:
+            creds = json.loads(_CREDENTIALS_FILE.read_text())
+            return creds.get(key)
+        except Exception:
+            pass
+    return None
+
+
+def delete_token(key: str) -> None:
+    try:
+        import keyring
+        keyring.delete_password(_KEYRING_SERVICE, key)
+    except Exception:
+        pass
+    if _CREDENTIALS_FILE.exists():
+        try:
+            creds = json.loads(_CREDENTIALS_FILE.read_text())
+            creds.pop(key, None)
+            _CREDENTIALS_FILE.write_text(json.dumps(creds))
+        except Exception:
+            pass

virtuai_cli/executor.py

@@ -0,0 +1,88 @@
+"""Execute commands and file operations inside the local workdir jail."""
+
+from __future__ import annotations
+
+import base64
+import subprocess
+from pathlib import Path
+from typing import Optional
+
+from virtuai_cli.security import check_command, jail_path, scrub_env
+
+_EXECUTE_TIMEOUT = 300  # seconds
+
+
+def execute(command: str, workdir: Path, timeout: int = _EXECUTE_TIMEOUT, extra_env: list[str] | None = None) -> dict:
+    """Run a shell command. Returns {output, exit_code}."""
+    denial = check_command(command)
+    if denial:
+        return {"output": f"blocked by local denylist: {denial}", "exit_code": 126}
+
+    env = scrub_env(workdir, extra_env)
+    try:
+        result = subprocess.run(
+            command,
+            shell=True,
+            cwd=str(workdir),
+            env=env,
+            capture_output=True,
+            timeout=timeout,
+        )
+        parts = []
+        if result.stdout:
+            parts.append(result.stdout.decode(errors="replace"))
+        if result.stderr:
+            parts.append(result.stderr.decode(errors="replace"))
+        return {"output": "\n".join(parts), "exit_code": result.returncode}
+    except subprocess.TimeoutExpired:
+        return {"output": f"command timed out after {timeout}s", "exit_code": 124}
+    except Exception as exc:
+        return {"output": f"executor error: {exc}", "exit_code": 1}
+
+
+def upload_files(files: list[dict], workdir: Path) -> list[dict]:
+    """Write files sent by the server. Rejects paths that escape the workdir."""
+    results = []
+    for f in files:
+        path_str: str = f["path"]
+        content_b64: str = f["content_b64"]
+
+        dest = jail_path(path_str, workdir)
+        if dest is None:
+            results.append({"path": path_str, "error": "path escapes workdir"})
+            continue
+
+        try:
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            dest.write_bytes(base64.b64decode(content_b64))
+            results.append({"path": path_str, "error": None})
+        except Exception as exc:
+            results.append({"path": path_str, "error": str(exc)})
+
+    return results
+
+
+def download_files(paths: list[str], workdir: Path) -> list[dict]:
+    """Read files for the server. Rejects paths that escape the workdir."""
+    results = []
+    for path_str in paths:
+        dest = jail_path(path_str, workdir)
+        if dest is None:
+            results.append({"path": path_str, "error": "path escapes workdir"})
+            continue
+
+        if not dest.exists():
+            results.append({"path": path_str, "error": "file_not_found"})
+            continue
+
+        try:
+            content = dest.read_bytes()
+            results.append({
+                "path": path_str,
+                "content_b64": base64.b64encode(content).decode(),
+                "error": None,
+            })
+        except Exception as exc:
+            results.append({"path": path_str, "error": str(exc)})
+
+    return results

virtuai_cli/main.py

@@ -0,0 +1,234 @@
+"""VirtuAI CLI — entry point."""
+
+from __future__ import annotations
+
+import asyncio
+import platform
+import socket
+import sys
+from pathlib import Path
+from typing import Optional
+
+import certifi
+import httpx
+
+# httpx doesn't use the macOS system keychain either; point it at certifi.
+_HTTPX_KWARGS: dict = {"verify": certifi.where()}
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from virtuai_cli import __version__
+from virtuai_cli import config as cfg
+
+app = typer.Typer(name="virtuai", help="Run VirtuAI deep agents on your local machine.", add_completion=False)
+console = Console()
+
+_DEFAULT_WORKDIR = Path.cwd()
+
+
+# ---------------------------------------------------------------------------
+# login — browser OAuth flow (opens the portal login page with a CLI callback)
+# ---------------------------------------------------------------------------
+
+@app.command()
+def login(
+    server: Optional[str] = typer.Option(None, "--server", help="VirtuAI server URL"),
+):
+    """Authenticate this CLI with your VirtuAI account."""
+    url = server or cfg.get_server_url()
+    cfg.set_key("server_url", url)
+    console.print(f"Opening [bold]{url}[/bold] in your browser …")
+    try:
+        import webbrowser
+        webbrowser.open(f"{url}/cli-login?cli=1")
+    except Exception:
+        console.print(f"[yellow]Could not open browser. Visit:[/yellow] {url}/cli-login?cli=1")
+
+    user_token = typer.prompt("Paste the token from the browser")
+    cfg.store_token(cfg._KEYRING_USER_TOKEN_KEY, user_token.strip())
+    cfg.set_key("server_url", url)
+    console.print("[green]Logged in.[/green]")
+
+
+# ---------------------------------------------------------------------------
+# pair — exchange a one-time code for a long-lived CLI token
+# ---------------------------------------------------------------------------
+
+@app.command()
+def pair(
+    code: str = typer.Argument(..., help="8-character pairing code from the VirtuAI portal"),
+    server: Optional[str] = typer.Option(None, "--server"),
+):
+    """Pair this machine with a VirtuAI workspace."""
+    url = server or cfg.get_server_url()
+    fingerprint = socket.gethostname()
+
+    console.print(f"Pairing with [bold]{url}[/bold] …")
+    try:
+        resp = httpx.post(
+            f"{url}/api/cli/pair/complete",
+            json={"code": code.upper(), "host_fingerprint": fingerprint},
+            timeout=15,
+            **_HTTPX_KWARGS,
+        )
+        resp.raise_for_status()
+        data = resp.json()
+    except httpx.HTTPStatusError as e:
+        console.print(f"[red]Error:[/red] {e.response.status_code} — {e.response.text}")
+        raise typer.Exit(1)
+    except Exception as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(1)
+
+    cli_token = data["cli_token"]
+    cfg.store_token(cfg._KEYRING_CLI_TOKEN_KEY, cli_token)
+    cfg.set_key("server_url", url)
+    console.print(f"[green]Paired.[/green] Run [bold]virtuai run[/bold] to start the local runner.")
+
+
+# ---------------------------------------------------------------------------
+# unpair — revoke this machine's pairing
+# ---------------------------------------------------------------------------
+
+@app.command()
+def unpair():
+    """Revoke the current pairing and clear stored credentials."""
+    token = cfg.load_token(cfg._KEYRING_CLI_TOKEN_KEY)
+    url = cfg.get_server_url()
+    user_token = cfg.load_token(cfg._KEYRING_USER_TOKEN_KEY)
+
+    if token and user_token:
+        try:
+            httpx.delete(
+                f"{url}/api/cli/pair",
+                headers={"Authorization": f"Bearer {user_token}"},
+                timeout=10,
+                **_HTTPX_KWARGS,
+            )
+        except Exception:
+            pass  # best-effort; we clear locally regardless
+
+    cfg.delete_token(cfg._KEYRING_CLI_TOKEN_KEY)
+    console.print("[yellow]Unpaired.[/yellow] CLI token cleared.")
+
+
+# ---------------------------------------------------------------------------
+# run — open the WebSocket and start accepting agent commands
+# ---------------------------------------------------------------------------
+
+@app.command()
+def run(
+    workdir: Optional[Path] = typer.Option(
+        None, "--workdir", help="Base directory for agent workspaces (default: ~/virtuai)"
+    ),
+    server: Optional[str] = typer.Option(None, "--server"),
+):
+    """Start the local runner. Keep this running while using VirtuAI."""
+    url = server or cfg.get_server_url()
+    token = cfg.load_token(cfg._KEYRING_CLI_TOKEN_KEY)
+    if not token:
+        console.print("[red]Not paired.[/red] Run [bold]virtuai pair <code>[/bold] first.")
+        raise typer.Exit(1)
+
+    base = workdir or _DEFAULT_WORKDIR
+    console.print(f"[bold]VirtuAI CLI[/bold] v{__version__} — Press Ctrl+C to stop.")
+
+    from virtuai_cli.runner import run_forever
+    try:
+        asyncio.run(run_forever(url, token, base))
+    except KeyboardInterrupt:
+        console.print("\n[yellow]Stopped.[/yellow]")
+
+
+# ---------------------------------------------------------------------------
+# status — show pairing and connection state
+# ---------------------------------------------------------------------------
+
+@app.command()
+def status(
+    server: Optional[str] = typer.Option(None, "--server"),
+):
+    """Show the current pairing and connection status."""
+    url = server or cfg.get_server_url()
+    user_token = cfg.load_token(cfg._KEYRING_USER_TOKEN_KEY)
+    cli_token = cfg.load_token(cfg._KEYRING_CLI_TOKEN_KEY)
+
+    table = Table(show_header=False)
+    table.add_row("Server", url)
+    table.add_row("CLI token", "stored" if cli_token else "[red]not paired[/red]")
+    table.add_row("User token", "stored" if user_token else "[yellow]not logged in[/yellow]")
+
+    if user_token and cli_token:
+        try:
+            workspace_id = cfg.get("workspace_id")
+            if workspace_id:
+                resp = httpx.get(
+                    f"{url}/api/cli/status",
+                    headers={
+                        "Authorization": f"Bearer {user_token}",
+                        "Workspace-ID": str(workspace_id),
+                    },
+                    timeout=5,
+                    **_HTTPX_KWARGS,
+                )
+                if resp.status_code == 200:
+                    data = resp.json()
+                    table.add_row("Connection", data.get("status", "?"))
+                    if data.get("workdir"):
+                        table.add_row("Workdir", data["workdir"])
+        except Exception:
+            table.add_row("Connection", "[dim]unknown[/dim]")
+
+    console.print(table)
+
+
+# ---------------------------------------------------------------------------
+# logs — show recent commands executed locally
+# ---------------------------------------------------------------------------
+
+@app.command()
+def logs(
+    tail: int = typer.Option(20, "--tail", "-n", help="Number of recent entries to show"),
+):
+    """Show recent commands executed by the agent on this machine."""
+    audit_file = Path.home() / ".virtuai" / "audit.log"
+    if not audit_file.exists():
+        console.print("[dim]No audit log yet.[/dim]")
+        return
+
+    lines = audit_file.read_text().splitlines()
+    for line in lines[-tail:]:
+        console.print(line)
+
+
+# ---------------------------------------------------------------------------
+# config — get/set local options
+# ---------------------------------------------------------------------------
+
+@app.command(name="config")
+def config_cmd(
+    action: str = typer.Argument(..., help="get or set"),
+    key: Optional[str] = typer.Argument(None),
+    value: Optional[str] = typer.Argument(None),
+):
+    """Get or set local CLI configuration."""
+    if action == "get":
+        if key:
+            console.print(cfg.get(key))
+        else:
+            import json
+            console.print(json.dumps(cfg.load(), indent=2))
+    elif action == "set":
+        if not key or value is None:
+            console.print("[red]Usage:[/red] virtuai config set <key> <value>")
+            raise typer.Exit(1)
+        cfg.set_key(key, value)
+        console.print(f"[green]Set[/green] {key} = {value}")
+    else:
+        console.print(f"[red]Unknown action:[/red] {action}")
+        raise typer.Exit(1)
+
+
+if __name__ == "__main__":
+    app()

virtuai_cli/runner.py

@@ -0,0 +1,155 @@
+"""WebSocket runner — connects to VirtuAI and dispatches agent commands."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import platform
+import sys
+import time
+from pathlib import Path
+from typing import Optional
+
+_AUDIT_DIR = Path.home() / ".virtuai"
+
+import websockets
+from rich.console import Console
+
+from virtuai_cli import __version__
+from virtuai_cli import executor as exec_
+from virtuai_cli.security import resolve_workdir
+
+logger = logging.getLogger(__name__)
+console = Console()
+
+
+def _audit(workdir: Path, command: str, exit_code: int, elapsed: float) -> None:
+    audit_file = _AUDIT_DIR / "audit.log"
+    _AUDIT_DIR.mkdir(parents=True, exist_ok=True)
+    try:
+        ts = time.strftime("%Y-%m-%dT%H:%M:%S")
+        line = f"{ts}\t{exit_code}\t{elapsed:.1f}s\t{command}\n"
+        with open(audit_file, "a") as fh:
+            fh.write(line)
+    except Exception:
+        pass
+
+_RECONNECT_DELAYS = [1, 2, 4, 8, 16, 30]  # backoff steps
+
+
+async def _handle_frame(frame: dict, workdir: Path, ws) -> None:
+    """Dispatch a server frame and send the result back."""
+    ftype = frame.get("type")
+    fid = frame.get("id")
+
+    if ftype == "hello":
+        reply = {
+            "v": 1,
+            "id": fid,
+            "type": "ready",
+            "cli_version": __version__,
+            "os": platform.system(),
+            "arch": platform.machine(),
+            "python": f"{sys.version_info.major}.{sys.version_info.minor}",
+            "workdir": str(workdir),
+        }
+        await ws.send(json.dumps(reply))
+        console.print(f"[green]Connected.[/green] Workdir: [bold]{workdir}[/bold]")
+        return
+
+    if ftype == "ping":
+        await ws.send(json.dumps({"v": 1, "id": fid, "type": "pong", "ts": time.time()}))
+        return
+
+    if ftype == "execute":
+        command = frame.get("command", "")
+        timeout = int(frame.get("timeout_secs", 300))
+        console.print(f"[dim]exec:[/dim] {command[:80]}{'...' if len(command) > 80 else ''}")
+        t0 = time.monotonic()
+        loop = asyncio.get_event_loop()
+        result = await loop.run_in_executor(
+            None, lambda: exec_.execute(command, workdir, timeout=timeout)
+        )
+        elapsed = time.monotonic() - t0
+        _audit(workdir, command, result["exit_code"], elapsed)
+        await ws.send(json.dumps({
+            "v": 1,
+            "id": fid,
+            "type": "execute_result",
+            "output": result["output"],
+            "exit_code": result["exit_code"],
+        }))
+        return
+
+    if ftype == "upload":
+        files = frame.get("files", [])
+        loop = asyncio.get_event_loop()
+        results = await loop.run_in_executor(None, lambda: exec_.upload_files(files, workdir))
+        await ws.send(json.dumps({"v": 1, "id": fid, "type": "upload_result", "results": results}))
+        return
+
+    if ftype == "download":
+        paths = frame.get("paths", [])
+        loop = asyncio.get_event_loop()
+        results = await loop.run_in_executor(None, lambda: exec_.download_files(paths, workdir))
+        await ws.send(json.dumps({"v": 1, "id": fid, "type": "download_result", "results": results}))
+        return
+
+    if ftype == "shutdown":
+        console.print(f"[yellow]Server requested shutdown:[/yellow] {frame.get('reason', '')}")
+        raise SystemExit(0)
+
+
+def _ssl_context():
+    """Return an SSL context that trusts certifi's CA bundle.
+
+    On macOS, the Python shipped by python.org doesn't use the system
+    keychain, so WSS connections fail with CERTIFICATE_VERIFY_FAILED unless
+    we explicitly point it at certifi's CA bundle.
+    """
+    import ssl
+    import certifi
+    ctx = ssl.create_default_context(cafile=certifi.where())
+    return ctx
+
+
+async def run_session(ws_url: str, token: str, workdir: Path) -> None:
+    """Run a single connected session until the WebSocket closes."""
+    url = f"{ws_url}?token={token}"
+    # Use certifi CA bundle for SSL so WSS works on macOS without the
+    # 'Install Certificates.command' workaround.
+    # Protocol-level pings disabled — the server sends application-level
+    # JSON pings every 20 s to keep the connection alive (cli_api/router.py).
+    ssl_ctx = _ssl_context() if ws_url.startswith("wss://") else None
+    async with websockets.connect(url, ping_interval=None, ssl=ssl_ctx) as ws:
+        async for raw in ws:
+            try:
+                frame = json.loads(raw)
+                await _handle_frame(frame, workdir, ws)
+            except SystemExit:
+                raise
+            except Exception as exc:
+                logger.warning("Frame handling error: %s", exc)
+
+
+async def run_forever(server_url: str, token: str, workdir: Path) -> None:
+    """Connect with exponential backoff, reconnecting on drop."""
+    ws_url = server_url.rstrip("/").replace("https://", "wss://").replace("http://", "ws://")
+    ws_url = f"{ws_url}/api/cli/ws"
+
+    workdir.mkdir(parents=True, exist_ok=True)
+    console.print(f"Connecting to [bold]{server_url}[/bold] …")
+
+    attempt = 0
+    while True:
+        try:
+            await run_session(ws_url, token, workdir)
+            attempt = 0  # successful session resets backoff
+        except SystemExit:
+            return
+        except Exception as exc:
+            delay = _RECONNECT_DELAYS[min(attempt, len(_RECONNECT_DELAYS) - 1)]
+            console.print(f"[red]Disconnected:[/red] {exc}. Retrying in {delay}s …")
+            await asyncio.sleep(delay)
+            attempt += 1

virtuai_cli/security.py

@@ -0,0 +1,88 @@
+"""Security helpers for the local sandbox executor.
+
+These run on the CLI side before forwarding a command to the local shell.
+The goal is a conservative default posture with documented trade-offs.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+from typing import Optional
+
+# ---------------------------------------------------------------------------
+# Workdir jail
+# ---------------------------------------------------------------------------
+
+def resolve_workdir(base: str) -> Path:
+    return Path(base).expanduser().resolve()
+
+
+def jail_path(path: str, workdir: Path) -> Optional[Path]:
+    """Return an absolute path only if it stays within workdir, else None."""
+    resolved = (workdir / path).resolve()
+    try:
+        resolved.relative_to(workdir)
+        return resolved
+    except ValueError:
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Command denylist
+# ---------------------------------------------------------------------------
+
+_DENYLIST: list[tuple[str, str]] = [
+    (r"\brm\s+-[rRf]*f[rRf]*\s+/\b", "rm -rf /"),
+    (r":\(\)\s*\{.*\|.*&\s*\}", "fork bomb"),
+    (r"\bmkfs\b", "mkfs"),
+    (r"\bdd\s+.*of=/dev/", "dd to device"),
+    (r"\bsudo\b", "sudo"),
+    (r"\bdoas\b", "doas"),
+    (r"\bpkexec\b", "pkexec"),
+    (r"\bchmod\s+777\s+/\b", "chmod 777 /"),
+]
+
+_DENYLIST_RE = [(re.compile(pattern, re.IGNORECASE), label) for pattern, label in _DENYLIST]
+
+
+def check_command(command: str) -> Optional[str]:
+    """Return a denial reason if the command matches the denylist, else None."""
+    for pattern, label in _DENYLIST_RE:
+        if pattern.search(command):
+            return label
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Environment scrubbing
+# ---------------------------------------------------------------------------
+
+_PASS_THROUGH_ENV = {
+    "PATH", "LANG", "TERM", "HOME", "SHELL",
+    "TMPDIR", "TMP", "TEMP",
+    # Some build tools need these
+    "USER", "LOGNAME",
+    "XDG_RUNTIME_DIR",
+}
+
+_VIRTUAI_ENV_PREFIX = "VIRTUAI_"
+
+
+def scrub_env(workdir: Path, extra_allow: list[str] | None = None) -> dict[str, str]:
+    """Build a clean environment: allowlist + VIRTUAI_ vars + user opt-ins."""
+    allowed = set(_PASS_THROUGH_ENV)
+    if extra_allow:
+        allowed.update(extra_allow)
+
+    env: dict[str, str] = {}
+    for key, value in os.environ.items():
+        if key in allowed or key.startswith(_VIRTUAI_ENV_PREFIX):
+            env[key] = value
+
+    # Keep REAL_HOME so the agent can resolve user paths, but override HOME
+    # so tools that write to ~/.cache/~/.config don't escape the workdir
+    env["REAL_HOME"] = env.get("HOME", os.path.expanduser("~"))
+    env["HOME"] = str(workdir)
+    return env

virtuai_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: virtuai-cli
+Version: 0.1.0
+Summary: Run VirtuAI deep agents on your local machine
+Author-email: uCloudStore <lmoreno@ucloudstore.com>
+License: Proprietary
+Project-URL: Homepage, https://imvituai.com
+Keywords: virtuai,ai,agents,cli
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: websockets>=12.0
+Requires-Dist: httpx[http2]>=0.27
+Requires-Dist: certifi>=2024.0
+Requires-Dist: keyring>=25.0
+Requires-Dist: typer>=0.12
+Requires-Dist: rich>=13.0
+
+# VirtuAI CLI
+
+Run VirtuAI deep agents on your local machine.
+
+## Installation
+
+```bash
+pip install virtuai-cli
+```
+
+Requires Python 3.11+.
+
+## Quick Start
+
+### 1. Pair your machine
+
+Open the VirtuAI portal, go to **Settings → CLI**, generate a pairing code, then run:
+
+```bash
+virtuai pair <CODE>
+```
+
+### 2. Start the local runner
+
+```bash
+virtuai run
+```
+
+Keep this terminal open while using VirtuAI. The agent can now execute shell commands on your machine.
+
+### 3. Stop
+
+Press `Ctrl+C` to stop the runner. Your workspace pairing persists.
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `virtuai pair <code>` | Pair this machine with a VirtuAI workspace |
+| `virtuai run` | Start the local runner |
+| `virtuai status` | Show pairing and connection status |
+| `virtuai logs` | Show recent commands executed by the agent |
+| `virtuai unpair` | Revoke the current pairing |
+| `virtuai login` | Authenticate with your VirtuAI account (browser flow) |
+
+## Options
+
+```
+virtuai run --workdir /path/to/dir   # Set a custom working directory
+virtuai run --server https://...     # Connect to a custom VirtuAI server
+```
+
+## Security
+
+- Commands run under your local user account with your file system permissions.
+- All communication is over encrypted WebSocket (WSS).
+- The agent can only run when `virtuai run` is active — no background daemon.
+- An audit log of executed commands is written to `~/.virtuai/audit.log`.

virtuai_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+virtuai_cli/__init__.py,sha256=WAcpXcqSfKeyt4mWbJBLFeoZnp9eXKxNa6b-hoU3TAk,47
+virtuai_cli/config.py,sha256=9VVbjeCkx2j2hJ4C4_PbWDN8xYe21FUv5OSyoxQkS3s,2911
+virtuai_cli/executor.py,sha256=iK8K9rV7zGGJj6X_US4VKVGDSQIHOsYUJ3sDVQsbUCM,2946
+virtuai_cli/main.py,sha256=hpM33n_wgSP6YgHnAOnelpJ-w5kjMZ0lFOin91Tbq4k,8271
+virtuai_cli/runner.py,sha256=50sHy3ECevzyX5gyXmyH1rWLRhGORjWRFFRfoeZRhc0,5490
+virtuai_cli/security.py,sha256=rWeGF4CyqoXN6o8DPrw2WTSBMv0gkbhtpTo5hlbF0OM,2805
+virtuai_cli-0.1.0.dist-info/METADATA,sha256=1XnbxiE9uRvYUK4o47eFd2FEjX2t_MXw2uCnR1zqKUM,2126
+virtuai_cli-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+virtuai_cli-0.1.0.dist-info/entry_points.txt,sha256=upSvW1pH9YVChKODbByxiYqdZ4gqa14wYagEeWhfQzQ,49
+virtuai_cli-0.1.0.dist-info/top_level.txt,sha256=mTSpGaMcoXDPdkEWKezmgAPNFziWSi2NiQAvsQ8YiD8,12
+virtuai_cli-0.1.0.dist-info/RECORD,,

virtuai_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

virtuai_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+virtuai = virtuai_cli.main:app

virtuai_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+virtuai_cli