safe-colab-cli 0.1.0__tar.gz

safe_colab_cli-0.1.0/PKG-INFO

@@ -0,0 +1,20 @@
+Metadata-Version: 2.4
+Name: safe-colab-cli
+Version: 0.1.0
+Summary: CLI tool for safe collaboration - sandboxed Jupyter kernel with remote Hypha service access
+Author: Amun AI AB
+License: MIT
+Keywords: safe-colab,sandbox,jupyter,hypha,remote-execution
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: hypha-rpc>=0.20.0
+Requires-Dist: jupyter_client>=8.0
+Requires-Dist: ipykernel>=6.0
+Requires-Dist: click>=8.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: sandbox
+Requires-Dist: nono-py>=0.1.0; extra == "sandbox"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"

safe_colab_cli-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "safe-colab-cli"
+version = "0.1.0"
+description = "CLI tool for safe collaboration - sandboxed Jupyter kernel with remote Hypha service access"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.9"
+authors = [{name = "Amun AI AB"}]
+keywords = ["safe-colab", "sandbox", "jupyter", "hypha", "remote-execution"]
+dependencies = [
+    "hypha-rpc>=0.20.0",
+    "jupyter_client>=8.0",
+    "ipykernel>=6.0",
+    "click>=8.0",
+    "python-dotenv>=1.0",
+    "httpx>=0.24.0",
+]
+
+[project.optional-dependencies]
+sandbox = [
+    "nono-py>=0.1.0",
+]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.21",
+]
+
+[project.scripts]
+safe-colab = "safe_colab_cli.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["safe_colab_cli*"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

safe_colab_cli-0.1.0/safe_colab_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Safe Colab CLI - Sandboxed Jupyter kernel with remote Hypha service access."""
+
+__version__ = "0.1.0"

safe_colab_cli-0.1.0/safe_colab_cli/__main__.py

@@ -0,0 +1,4 @@
+"""Allow running as python -m safe_colab_cli."""
+from .cli import main
+
+main()

safe_colab_cli-0.1.0/safe_colab_cli/artifacts.py

@@ -0,0 +1,181 @@
+"""Artifact manager integration for file sharing, logging, and auditing.
+
+Creates a collection per user and a child artifact per session.
+Files (plots, results, large datasets) are uploaded to the artifact manager
+and shared via presigned URLs - no data copying needed.
+"""
+
+import os
+import time
+import json
+import secrets
+import logging
+from datetime import datetime, timezone
+from typing import Optional
+
+import httpx
+
+logger = logging.getLogger("safe_colab_cli.artifacts")
+
+COLLECTION_ALIAS = "safe-colab-sessions"
+
+
+class SessionArtifactManager:
+    """Manages artifacts for a single safe-colab session.
+
+    Creates a collection (if needed) and a session artifact within it.
+    Provides upload/download via presigned URLs and audit logging.
+    """
+
+    def __init__(self, artifact_manager, session_id: str, workspace: str):
+        self._am = artifact_manager
+        self.session_id = session_id
+        self.workspace = workspace
+        self.collection_id = None
+        self.artifact_id = None
+        self._log_buffer = []
+
+    async def initialize(self):
+        """Create the collection (idempotent) and session artifact."""
+        # Ensure collection exists
+        try:
+            collection = await self._am.read(artifact_id=COLLECTION_ALIAS)
+            self.collection_id = collection["id"]
+        except Exception:
+            collection = await self._am.create(
+                type="collection",
+                alias=COLLECTION_ALIAS,
+                manifest={
+                    "name": "Safe Colab Sessions",
+                    "description": "Collection of safe-colab session artifacts for auditing and file sharing",
+                },
+                config={
+                    "permissions": {"@": "rw+"},
+                },
+                stage=True,
+            )
+            self.collection_id = collection["id"]
+            try:
+                await self._am.commit(self.collection_id)
+            except Exception:
+                pass  # Already committed or no staging needed
+
+        # Create session artifact
+        session_alias = f"session-{self.session_id[:12]}"
+        artifact = await self._am.create(
+            type="dataset",
+            alias=session_alias,
+            parent_id=self.collection_id,
+            manifest={
+                "name": f"Session {self.session_id[:8]}",
+                "description": f"Safe Colab session started at {datetime.now(timezone.utc).isoformat()}",
+                "session_id": self.session_id,
+                "created_at": datetime.now(timezone.utc).isoformat(),
+            },
+            stage=True,
+        )
+        self.artifact_id = artifact["id"]
+        logger.info(f"Session artifact created: {self.artifact_id}")
+
+        # Write initial audit log entry
+        await self.log_event("session_start", {"session_id": self.session_id})
+
+    async def upload_file(self, local_path: str, remote_path: Optional[str] = None) -> str:
+        """Upload a file and return a presigned download URL.
+
+        Args:
+            local_path: Local file path to upload.
+            remote_path: Path within the artifact (defaults to filename).
+
+        Returns:
+            Presigned download URL for the uploaded file.
+        """
+        if remote_path is None:
+            remote_path = os.path.basename(local_path)
+
+        put_url = await self._am.put_file(self.artifact_id, file_path=remote_path)
+
+        async with httpx.AsyncClient() as client:
+            with open(local_path, "rb") as f:
+                resp = await client.put(put_url, content=f.read())
+                resp.raise_for_status()
+
+        # Get download URL
+        get_url = await self._am.get_file(self.artifact_id, file_path=remote_path)
+
+        await self.log_event("file_upload", {
+            "local_path": local_path,
+            "remote_path": remote_path,
+            "size_bytes": os.path.getsize(local_path),
+        })
+
+        return get_url
+
+    async def upload_bytes(self, data: bytes, remote_path: str, content_type: str = "application/octet-stream") -> str:
+        """Upload raw bytes and return a presigned download URL."""
+        put_url = await self._am.put_file(self.artifact_id, file_path=remote_path)
+
+        async with httpx.AsyncClient() as client:
+            resp = await client.put(put_url, content=data, headers={"Content-Type": content_type})
+            resp.raise_for_status()
+
+        get_url = await self._am.get_file(self.artifact_id, file_path=remote_path)
+
+        await self.log_event("bytes_upload", {
+            "remote_path": remote_path,
+            "size_bytes": len(data),
+            "content_type": content_type,
+        })
+
+        return get_url
+
+    async def get_download_url(self, remote_path: str) -> str:
+        """Get a presigned download URL for an existing file."""
+        return await self._am.get_file(self.artifact_id, file_path=remote_path)
+
+    async def list_files(self) -> list:
+        """List all files in the session artifact."""
+        return await self._am.list_files(self.artifact_id)
+
+    async def log_event(self, event_type: str, details: dict):
+        """Append an audit log entry to the session artifact."""
+        entry = {
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "event": event_type,
+            **details,
+        }
+        self._log_buffer.append(entry)
+
+        # Write log file periodically (every event for now)
+        log_content = "\n".join(json.dumps(e) for e in self._log_buffer) + "\n"
+        try:
+            put_url = await self._am.put_file(self.artifact_id, file_path="audit_log.jsonl")
+            async with httpx.AsyncClient() as client:
+                await client.put(put_url, content=log_content.encode())
+        except Exception as e:
+            logger.warning(f"Failed to write audit log: {e}")
+
+    async def log_code_execution(self, code: str, result: dict):
+        """Log a code execution event for auditing."""
+        await self.log_event("code_execution", {
+            "code_length": len(code),
+            "code_preview": code[:200] + ("..." if len(code) > 200 else ""),
+            "has_error": result.get("error") is not None,
+            "stdout_length": len(result.get("stdout", "")),
+        })
+
+    async def log_command_execution(self, command: str, result: dict):
+        """Log a shell command execution event."""
+        await self.log_event("command_execution", {
+            "command": command[:200],
+            "returncode": result.get("returncode"),
+        })
+
+    async def commit(self, version: Optional[str] = None):
+        """Commit the session artifact (makes files permanent)."""
+        await self._am.commit(
+            self.artifact_id,
+            version=version,
+            comment=f"Session {self.session_id[:8]} committed",
+        )
+        logger.info(f"Session artifact committed: {self.artifact_id}")

safe_colab_cli-0.1.0/safe_colab_cli/cli.py

@@ -0,0 +1,173 @@
+"""CLI entry point for safe-colab."""
+
+import asyncio
+import os
+import signal
+import sys
+
+import click
+from dotenv import load_dotenv
+
+# Load .env before click parses envvar options
+# override=True so .env takes priority over inherited env vars (e.g. from parent Svamp session)
+load_dotenv(override=True)
+
+
+@click.group()
+def main():
+    """Safe Colab CLI - Sandboxed Python environment for safe AI collaboration."""
+    pass
+
+
+@main.command()
+@click.option("--data-dir", "-d", type=click.Path(exists=True), default=None,
+              help="Read-only data directory to mount (accessible as /data in sandbox)")
+@click.option("--work-dir", "-w", type=click.Path(), default="./workspace",
+              help="Read-write working directory (accessible as /workspace in sandbox)")
+@click.option("--server-url", envvar="HYPHA_SERVER_URL", default="https://hypha.aicell.io",
+              help="Hypha server URL")
+@click.option("--workspace", envvar="HYPHA_WORKSPACE", default="safe-colab",
+              help="Hypha workspace name")
+@click.option("--token", envvar="HYPHA_TOKEN", default=None,
+              help="Hypha authentication token")
+@click.option("--no-sandbox", is_flag=True, default=False,
+              help="Disable nono sandbox (for development/testing)")
+@click.option("--timeout", type=float, default=120,
+              help="Default code execution timeout in seconds")
+def start(data_dir, work_dir, server_url, workspace, token, no_sandbox, timeout):
+    """Start a sandboxed Safe Colab session.
+
+    Launches a Jupyter kernel in a sandboxed environment and registers
+    it as a Hypha service for remote code execution.
+    """
+
+    if not token:
+        click.echo("Error: No authentication token provided. Set HYPHA_TOKEN or use --token", err=True)
+        sys.exit(1)
+
+    # Ensure work directory exists
+    os.makedirs(work_dir, exist_ok=True)
+    abs_work_dir = os.path.abspath(work_dir)
+    abs_data_dir = os.path.abspath(data_dir) if data_dir else None
+
+    click.echo("=" * 60)
+    click.echo("  Safe Colab CLI - Starting Session")
+    click.echo("=" * 60)
+    click.echo(f"  Server:    {server_url}")
+    click.echo(f"  Workspace: {workspace}")
+    if abs_data_dir:
+        click.echo(f"  Data dir:  {abs_data_dir} (read-only)")
+    click.echo(f"  Work dir:  {abs_work_dir} (read-write)")
+    click.echo(f"  Sandbox:   {'disabled' if no_sandbox else 'enabled'}")
+    click.echo("=" * 60)
+    click.echo()
+
+    asyncio.run(_run_session(
+        server_url=server_url,
+        workspace=workspace,
+        token=token,
+        data_dir=abs_data_dir,
+        work_dir=abs_work_dir,
+        no_sandbox=no_sandbox,
+        timeout=timeout,
+    ))
+
+
+async def _run_session(server_url, workspace, token, data_dir, work_dir, no_sandbox, timeout):
+    """Main async session loop."""
+    from .kernel import SandboxKernel
+    from .service import register_service
+
+    kernel = SandboxKernel()
+
+    # Prepare kernel environment
+    kernel_env = {}
+    if data_dir:
+        kernel_env["SAFE_COLAB_DATA_DIR"] = data_dir
+    kernel_env["SAFE_COLAB_WORK_DIR"] = work_dir
+
+    # Start the Jupyter kernel
+    click.echo("[1/3] Starting Jupyter kernel...")
+    await kernel.start(env=kernel_env)
+
+    # Set up working directories inside the kernel
+    setup_code = f"""
+import os, sys
+# Set up directory aliases
+_data_dir = {repr(data_dir) if data_dir else 'None'}
+_work_dir = {repr(work_dir)}
+os.chdir(_work_dir)
+if _data_dir and not os.path.exists('/data'):
+    # Create symlink for convenience (may fail in sandbox)
+    try:
+        os.symlink(_data_dir, '/data')
+    except (OSError, PermissionError):
+        pass
+print(f"Working directory: {{os.getcwd()}}")
+if _data_dir:
+    print(f"Data directory: {{_data_dir}}")
+    if os.path.exists(_data_dir):
+        print(f"Data files: {{os.listdir(_data_dir)[:20]}}")
+"""
+    result = await kernel.execute(setup_code)
+    if result["stdout"]:
+        click.echo(f"  {result['stdout'].strip()}")
+    if result["error"]:
+        click.echo(f"  Warning: {result['error']['evalue']}")
+
+    # Apply sandbox (if enabled)
+    if not no_sandbox:
+        click.echo("[2/3] Setting up sandbox...")
+        from .sandbox import setup_sandbox
+        sandboxed = setup_sandbox(data_dir, work_dir)
+        if not sandboxed:
+            click.echo("  Continuing without sandbox")
+    else:
+        click.echo("[2/3] Sandbox disabled")
+
+    # Register Hypha service
+    click.echo("[3/3] Registering Hypha service...")
+    server, svc_info, instructions, service_url = await register_service(
+        server_url=server_url,
+        workspace=workspace,
+        token=token,
+        kernel=kernel,
+        data_dir=data_dir or "(none)",
+        work_dir=work_dir,
+    )
+
+    click.echo()
+    click.echo("=" * 60)
+    click.echo("  Session Ready!")
+    click.echo("=" * 60)
+    click.echo(f"  Service URL: {service_url}")
+    click.echo()
+    click.echo("Copy the instructions below and paste them to your AI agent:")
+    click.echo()
+    click.echo("-" * 60)
+    click.echo(instructions)
+    click.echo("-" * 60)
+    click.echo()
+    click.echo("Press Ctrl+C to stop the session.")
+    click.echo()
+
+    # Keep running until interrupted
+    stop_event = asyncio.Event()
+
+    def _signal_handler():
+        click.echo("\n[session] Shutting down...")
+        stop_event.set()
+
+    loop = asyncio.get_event_loop()
+    for sig in (signal.SIGINT, signal.SIGTERM):
+        loop.add_signal_handler(sig, _signal_handler)
+
+    await stop_event.wait()
+
+    # Cleanup
+    await kernel.stop()
+    click.echo("[session] Session ended.")
+
+
+if __name__ == "__main__":
+    main()

safe_colab_cli-0.1.0/safe_colab_cli/kernel.py

@@ -0,0 +1,93 @@
+"""Jupyter kernel manager - starts and communicates with a local IPython kernel."""
+
+import asyncio
+import uuid
+from jupyter_client import KernelManager
+
+
+class SandboxKernel:
+    """Manages a Jupyter IPython kernel for code execution."""
+
+    def __init__(self):
+        self._km = None
+        self._kc = None
+
+    async def start(self, env=None):
+        """Start the Jupyter kernel."""
+        self._km = KernelManager(kernel_name="python3")
+        if env:
+            self._km.kernel_spec_manager  # ensure spec is loaded
+            # Extra env vars passed to the kernel process
+            self._km.extra_env = env
+        self._km.start_kernel()
+        self._kc = self._km.client()
+        self._kc.start_channels()
+        # Wait for kernel to be ready
+        await asyncio.get_event_loop().run_in_executor(
+            None, self._kc.wait_for_ready, 30
+        )
+        print("[kernel] IPython kernel started")
+
+    async def execute(self, code: str, timeout: float = 120) -> dict:
+        """Execute code and return results.
+
+        Returns dict with keys: stdout, stderr, result, error, display_data
+        """
+        msg_id = self._kc.execute(code)
+        return await asyncio.get_event_loop().run_in_executor(
+            None, self._collect_output, msg_id, timeout
+        )
+
+    def _collect_output(self, msg_id: str, timeout: float) -> dict:
+        """Collect all output messages for an execution request (blocking)."""
+        stdout_parts = []
+        stderr_parts = []
+        result = None
+        error = None
+        display_data = []
+
+        while True:
+            try:
+                msg = self._kc.get_iopub_msg(timeout=timeout)
+            except Exception:
+                break
+
+            if msg["parent_header"].get("msg_id") != msg_id:
+                continue
+
+            msg_type = msg["msg_type"]
+            content = msg["content"]
+
+            if msg_type == "stream":
+                if content["name"] == "stdout":
+                    stdout_parts.append(content["text"])
+                elif content["name"] == "stderr":
+                    stderr_parts.append(content["text"])
+            elif msg_type == "execute_result":
+                result = content["data"].get("text/plain", "")
+            elif msg_type == "display_data":
+                display_data.append(content["data"])
+            elif msg_type == "error":
+                error = {
+                    "ename": content["ename"],
+                    "evalue": content["evalue"],
+                    "traceback": content["traceback"],
+                }
+            elif msg_type == "status" and content["execution_state"] == "idle":
+                break
+
+        return {
+            "stdout": "".join(stdout_parts),
+            "stderr": "".join(stderr_parts),
+            "result": result,
+            "error": error,
+            "display_data": display_data,
+        }
+
+    async def stop(self):
+        """Shut down the kernel."""
+        if self._kc:
+            self._kc.stop_channels()
+        if self._km:
+            self._km.shutdown_kernel(now=True)
+        print("[kernel] Kernel stopped")

safe_colab_cli-0.1.0/safe_colab_cli/sandbox.py

@@ -0,0 +1,73 @@
+"""Nono sandbox integration - applies filesystem restrictions to the kernel process."""
+
+import os
+import sys
+
+
+def setup_sandbox(data_dir: str, work_dir: str):
+    """Apply nono sandbox to the current process.
+
+    This restricts filesystem access to:
+    - data_dir: read-only
+    - work_dir: read-write
+    - Python/system paths: read-only (for imports to work)
+
+    NOTE: This is irreversible. Once applied, permissions cannot be expanded.
+    """
+    try:
+        from nono_py import CapabilitySet, AccessMode, apply, is_supported
+    except ImportError:
+        print("[sandbox] WARNING: nono_py not installed. Running WITHOUT sandbox.")
+        print("[sandbox] Install with: pip install nono-py")
+        return False
+
+    if not is_supported():
+        print("[sandbox] WARNING: Platform does not support sandboxing. Running WITHOUT sandbox.")
+        return False
+
+    caps = CapabilitySet()
+
+    # Data directory: read-only
+    if data_dir:
+        abs_data = os.path.abspath(data_dir)
+        caps.allow_path(abs_data, AccessMode.READ)
+        print(f"[sandbox] Data dir (read-only): {abs_data}")
+
+    # Working directory: read-write
+    abs_work = os.path.abspath(work_dir)
+    caps.allow_path(abs_work, AccessMode.READ_WRITE)
+    print(f"[sandbox] Work dir (read-write): {abs_work}")
+
+    # Allow Python paths (read-only) so imports work
+    for path in sys.path:
+        if path and os.path.isdir(path):
+            caps.allow_path(path, AccessMode.READ)
+
+    # Allow standard system paths needed by Python
+    system_paths = [
+        sys.prefix,
+        sys.exec_prefix,
+        "/usr/lib",
+        "/usr/local/lib",
+        "/usr/share",
+        "/etc",  # needed for some configs
+    ]
+    if hasattr(sys, "base_prefix"):
+        system_paths.append(sys.base_prefix)
+    if hasattr(sys, "base_exec_prefix"):
+        system_paths.append(sys.base_exec_prefix)
+
+    for p in system_paths:
+        if p and os.path.isdir(p):
+            caps.allow_path(p, AccessMode.READ)
+
+    # Allow /tmp for temp files (read-write)
+    if os.path.isdir("/tmp"):
+        caps.allow_path("/tmp", AccessMode.READ_WRITE)
+
+    # Don't block network - needed for Hypha communication
+    # (nono allows network by default)
+
+    apply(caps)
+    print("[sandbox] Sandbox applied successfully")
+    return True

safe_colab_cli-0.1.0/safe_colab_cli/service.py

@@ -0,0 +1,302 @@
+"""Hypha service registration - exposes code execution, shell commands, and file sharing."""
+
+import os
+import secrets
+import asyncio
+import subprocess
+import base64
+import json
+from hypha_rpc import connect_to_server
+
+from .artifacts import SessionArtifactManager
+
+
+def _build_service_url(server_url: str, service_id: str) -> str:
+    """Build the HTTP service URL, stripping the clientId prefix."""
+    base = server_url.rstrip("/")
+    parts = service_id.split("/", 1)
+    if len(parts) == 2:
+        workspace, svc_part = parts
+        if ":" in svc_part:
+            svc_name = svc_part.split(":", 1)[1]
+        else:
+            svc_name = svc_part
+        return f"{base}/{workspace}/services/{svc_name}"
+    return f"{base}/services/{service_id}"
+
+
+def _build_agent_instructions(service_url: str, data_dir: str, work_dir: str) -> str:
+    """Build agent instructions with curl examples for all endpoints."""
+    return f"""\
+## Safe Colab - Remote Code Execution Environment
+
+You have access to a sandboxed Python environment on a remote machine.
+The service URL below acts as a secret — no additional token is needed.
+
+**Service URL:** `{service_url}`
+
+### Endpoints
+
+#### 1. `run_code(code: str) -> dict`
+Execute Python code in a persistent Jupyter kernel. Variables and imports persist across calls.
+```bash
+curl -s -X POST "$SERVICE_URL/run_code" \\
+  -H "Content-Type: application/json" \\
+  -d '{{"code": "import pandas as pd; df = pd.read_csv(\\"{data_dir}/patient_health.csv\\"); print(df.shape)"}}'
+```
+Returns: `{{"stdout": "...", "stderr": "...", "result": "...", "error": null | {{"ename": "...", "evalue": "...", "traceback": [...]}}, "display_data": [...]}}`
+
+#### 2. `execute_command(command: str, timeout: int = 60) -> dict`
+Run shell commands (pip install, ls, cat, wget, etc.).
+```bash
+curl -s -X POST "$SERVICE_URL/execute_command" \\
+  -H "Content-Type: application/json" \\
+  -d '{{"command": "pip install scikit-learn matplotlib"}}'
+```
+Returns: `{{"stdout": "...", "stderr": "...", "returncode": 0}}`
+
+#### 3. `upload_file(file_path: str, remote_name: str = None) -> dict`
+Upload a file from the working directory to the shared artifact store. Returns a presigned download URL.
+```bash
+curl -s -X POST "$SERVICE_URL/upload_file" \\
+  -H "Content-Type: application/json" \\
+  -d '{{"file_path": "{work_dir}/results.csv"}}'
+```
+Returns: `{{"url": "https://...", "remote_path": "results.csv"}}`
+
+#### 4. `list_shared_files() -> list`
+List all files uploaded to the session artifact store.
+
+#### 5. `get_docs() -> str`
+Get detailed documentation about the environment.
+
+### Environment Details
+- **Data directory** (read-only): `{data_dir}` — dataset files
+- **Working directory** (read-write): `{work_dir}` — outputs, results, logs
+- Full Python 3 with pip. Install packages via `execute_command("pip install <pkg>")`
+- Jupyter kernel state persists across `run_code` calls
+- Generated files (plots, CSVs) can be shared via `upload_file` — returns a URL
+
+### Quick Start
+```bash
+SERVICE_URL="{service_url}"
+
+# 1. Check what data is available
+curl -s -X POST "$SERVICE_URL/execute_command" -H "Content-Type: application/json" \\
+  -d '{{"command": "ls -la {data_dir}"}}'
+
+# 2. Install needed packages
+curl -s -X POST "$SERVICE_URL/execute_command" -H "Content-Type: application/json" \\
+  -d '{{"command": "pip install pandas matplotlib scikit-learn"}}'
+
+# 3. Run analysis code
+curl -s -X POST "$SERVICE_URL/run_code" -H "Content-Type: application/json" \\
+  -d '{{"code": "import pandas as pd\\ndf = pd.read_csv(\\\"{data_dir}/patient_health.csv\\\")\\nprint(df.describe())"}}'
+
+# 4. Save and share results
+curl -s -X POST "$SERVICE_URL/run_code" -H "Content-Type: application/json" \\
+  -d '{{"code": "df.to_csv(\\\"{work_dir}/output.csv\\\", index=False)\\nprint(\\\"saved\\\")"}}'
+curl -s -X POST "$SERVICE_URL/upload_file" -H "Content-Type: application/json" \\
+  -d '{{"file_path": "{work_dir}/output.csv"}}'
+```
+
+### Rules
+- Do NOT access files outside the data and working directories
+- The environment is sandboxed — filesystem access is restricted
+- Large outputs are truncated to 50KB
+- Code execution timeout: 120 seconds per cell
+- All code executions and commands are logged for auditing
+"""
+
+
+async def register_service(
+    server_url: str,
+    workspace: str,
+    token: str,
+    kernel,
+    data_dir: str,
+    work_dir: str,
+    session_id: str = None,
+):
+    """Connect to Hypha and register the code execution service.
+
+    Registers as unlisted with a random service ID (URL-as-secret pattern).
+    Returns (server, service_info, agent_instructions, service_url).
+    """
+    if session_id is None:
+        session_id = secrets.token_hex(16)
+
+    server = await connect_to_server({
+        "server_url": server_url,
+        "workspace": workspace,
+        "token": token,
+    })
+    actual_workspace = (
+        server.config.get("workspace", workspace)
+        if hasattr(server.config, "get")
+        else getattr(server.config, "workspace", workspace)
+    )
+    print(f"[hypha] Connected to {server_url}, workspace: {actual_workspace}")
+
+    # Initialize artifact manager for file sharing and audit logging
+    artifact_mgr = None
+    try:
+        am_service = await server.get_service("public/artifact-manager")
+        artifact_mgr = SessionArtifactManager(am_service, session_id, actual_workspace)
+        await artifact_mgr.initialize()
+        print(f"[hypha] Session artifact created for file sharing and audit logging")
+    except Exception as e:
+        print(f"[hypha] Warning: Artifact manager not available ({e}). File sharing disabled.")
+
+    # ── Endpoint: run_code ──
+    async def run_code(code: str) -> dict:
+        """Execute Python code in the sandboxed Jupyter kernel.
+        Variables and imports persist across calls."""
+        result = await kernel.execute(code)
+        max_len = 50000
+        for key in ("stdout", "stderr"):
+            if result[key] and len(result[key]) > max_len:
+                result[key] = result[key][:max_len] + "\n... (truncated)"
+        # Audit log
+        if artifact_mgr:
+            try:
+                await artifact_mgr.log_code_execution(code, result)
+            except Exception:
+                pass
+        return result
+
+    # ── Endpoint: execute_command ──
+    # Build env with venv's bin on PATH so pip/python resolve correctly
+    import sys
+    _cmd_env = os.environ.copy()
+    _venv_bin = os.path.dirname(sys.executable)
+    _cmd_env["PATH"] = _venv_bin + os.pathsep + _cmd_env.get("PATH", "")
+    _cmd_env["VIRTUAL_ENV"] = os.path.dirname(_venv_bin)
+
+    async def execute_command(command: str, timeout: int = 60) -> dict:
+        """Execute a shell command in the working directory.
+        Use for pip install, file listing, system tools, etc."""
+        try:
+            proc = await asyncio.get_event_loop().run_in_executor(
+                None,
+                lambda: subprocess.run(
+                    command, shell=True, capture_output=True, text=True,
+                    timeout=timeout, cwd=work_dir, env=_cmd_env,
+                ),
+            )
+            result = {"stdout": proc.stdout, "stderr": proc.stderr, "returncode": proc.returncode}
+            max_len = 50000
+            for key in ("stdout", "stderr"):
+                if len(result[key]) > max_len:
+                    result[key] = result[key][:max_len] + "\n... (truncated)"
+        except subprocess.TimeoutExpired:
+            result = {"stdout": "", "stderr": f"Command timed out after {timeout}s", "returncode": -1}
+        # Audit log
+        if artifact_mgr:
+            try:
+                await artifact_mgr.log_command_execution(command, result)
+            except Exception:
+                pass
+        return result
+
+    # ── Endpoint: upload_file ──
+    async def upload_file(file_path: str, remote_name: str = None) -> dict:
+        """Upload a file from the working directory to the shared artifact store.
+        Returns a presigned download URL for the remote agent."""
+        if artifact_mgr is None:
+            return {"error": "Artifact manager not available. File sharing is disabled."}
+
+        # Security: only allow files within work_dir or data_dir
+        abs_path = os.path.abspath(file_path)
+        allowed = abs_path.startswith(os.path.abspath(work_dir))
+        if data_dir and data_dir != "(none)":
+            allowed = allowed or abs_path.startswith(os.path.abspath(data_dir))
+        if not allowed:
+            return {"error": f"Access denied: file must be within work_dir or data_dir"}
+
+        if not os.path.exists(abs_path):
+            return {"error": f"File not found: {file_path}"}
+
+        if remote_name is None:
+            remote_name = os.path.basename(abs_path)
+
+        try:
+            url = await artifact_mgr.upload_file(abs_path, remote_name)
+            return {"url": url, "remote_path": remote_name}
+        except Exception as e:
+            return {"error": f"Upload failed: {str(e)}"}
+
+    # ── Endpoint: list_shared_files ──
+    async def list_shared_files() -> list:
+        """List all files uploaded to the session artifact store."""
+        if artifact_mgr is None:
+            return []
+        try:
+            return await artifact_mgr.list_files()
+        except Exception:
+            return []
+
+    # ── Endpoint: get_docs ──
+    async def get_docs() -> str:
+        """Get documentation about the sandboxed environment."""
+        return f"""# Safe Colab Environment
+
+## Data Directory (read-only): {data_dir}
+Contains the dataset files provided by the data owner.
+
+## Working Directory (read-write): {work_dir}
+Write outputs, logs, results, and reports here.
+
+## Available Endpoints
+- `run_code(code)` — Execute Python (persistent kernel, like Jupyter)
+- `execute_command(command)` — Run shell commands (pip, ls, cat, etc.)
+- `upload_file(file_path)` — Upload file to artifact store, get shareable URL
+- `list_shared_files()` — List uploaded files
+- `get_docs()` — This documentation
+
+## Capabilities
+- Full Python 3 environment with persistent Jupyter kernel
+- Install any pip package: `execute_command("pip install numpy pandas matplotlib")`
+- Read data files from {data_dir}
+- Write results to {work_dir}
+- Share large files (plots, datasets) via `upload_file()` → returns download URL
+
+## Tips
+- Install packages FIRST with execute_command before using them in run_code
+- Variables persist across run_code calls (like Jupyter cells)
+- For large outputs, write to file then upload_file() instead of printing
+- All operations are logged for auditing
+"""
+
+    # ── Register service ──
+    service_id = f"safe-colab-{secrets.token_hex(16)}"
+
+    svc_info = await server.register_service({
+        "id": service_id,
+        "name": "Safe Colab Sandbox",
+        "type": "code-interpreter",
+        "description": "Sandboxed Python environment for safe remote code execution",
+        "config": {
+            "visibility": "unlisted",
+            "require_context": False,
+            "run_in_executor": True,
+        },
+        "run_code": run_code,
+        "execute_command": execute_command,
+        "upload_file": upload_file,
+        "list_shared_files": list_shared_files,
+        "get_docs": get_docs,
+    })
+
+    actual_id = svc_info.get("id", service_id) if isinstance(svc_info, dict) else service_id
+    service_url = _build_service_url(server_url, actual_id)
+
+    instructions = _build_agent_instructions(
+        service_url=service_url,
+        data_dir=data_dir,
+        work_dir=work_dir,
+    )
+
+    print(f"[hypha] Service registered: {actual_id}")
+    print(f"[hypha] Service URL: {service_url}")
+    return server, svc_info, instructions, service_url

safe_colab_cli-0.1.0/safe_colab_cli.egg-info/PKG-INFO

@@ -0,0 +1,20 @@
+Metadata-Version: 2.4
+Name: safe-colab-cli
+Version: 0.1.0
+Summary: CLI tool for safe collaboration - sandboxed Jupyter kernel with remote Hypha service access
+Author: Amun AI AB
+License: MIT
+Keywords: safe-colab,sandbox,jupyter,hypha,remote-execution
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: hypha-rpc>=0.20.0
+Requires-Dist: jupyter_client>=8.0
+Requires-Dist: ipykernel>=6.0
+Requires-Dist: click>=8.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: sandbox
+Requires-Dist: nono-py>=0.1.0; extra == "sandbox"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"

safe_colab_cli-0.1.0/safe_colab_cli.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+pyproject.toml
+safe_colab_cli/__init__.py
+safe_colab_cli/__main__.py
+safe_colab_cli/artifacts.py
+safe_colab_cli/cli.py
+safe_colab_cli/kernel.py
+safe_colab_cli/sandbox.py
+safe_colab_cli/service.py
+safe_colab_cli.egg-info/PKG-INFO
+safe_colab_cli.egg-info/SOURCES.txt
+safe_colab_cli.egg-info/dependency_links.txt
+safe_colab_cli.egg-info/entry_points.txt
+safe_colab_cli.egg-info/requires.txt
+safe_colab_cli.egg-info/top_level.txt
+tests/test_e2e.py
+tests/test_kernel.py

safe_colab_cli-0.1.0/safe_colab_cli.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

safe_colab_cli-0.1.0/safe_colab_cli.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+safe-colab = safe_colab_cli.cli:main

safe_colab_cli-0.1.0/safe_colab_cli.egg-info/requires.txt

@@ -0,0 +1,13 @@
+hypha-rpc>=0.20.0
+jupyter_client>=8.0
+ipykernel>=6.0
+click>=8.0
+python-dotenv>=1.0
+httpx>=0.24.0
+
+[dev]
+pytest>=7.0
+pytest-asyncio>=0.21
+
+[sandbox]
+nono-py>=0.1.0

safe_colab_cli-0.1.0/safe_colab_cli.egg-info/top_level.txt

@@ -0,0 +1 @@
+safe_colab_cli

safe_colab_cli-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

safe_colab_cli-0.1.0/tests/test_e2e.py

@@ -0,0 +1,143 @@
+"""End-to-end test: kernel + Hypha service + artifacts + remote code execution."""
+
+import os
+import pytest
+from dotenv import load_dotenv
+
+from safe_colab_cli.kernel import SandboxKernel
+from safe_colab_cli.service import register_service
+
+# Load .env for credentials
+load_dotenv(os.path.join(os.path.dirname(__file__), "..", ".env"), override=True)
+
+SERVER_URL = os.environ.get("HYPHA_SERVER_URL", "https://hypha.aicell.io")
+WORKSPACE = os.environ.get("HYPHA_WORKSPACE", "safe-colab")
+TOKEN = os.environ.get("HYPHA_TOKEN")
+
+
+@pytest.fixture
+async def kernel():
+    k = SandboxKernel()
+    await k.start()
+    yield k
+    await k.stop()
+
+
+@pytest.mark.asyncio
+@pytest.mark.skipif(not TOKEN, reason="HYPHA_TOKEN not set")
+async def test_e2e_full_workflow(kernel, tmp_path):
+    """Full end-to-end: register, run code, shell commands, upload files, list files."""
+    work_dir = str(tmp_path / "workspace")
+    os.makedirs(work_dir, exist_ok=True)
+    data_dir = str(tmp_path / "data")
+    os.makedirs(data_dir, exist_ok=True)
+
+    # Create test data
+    with open(os.path.join(data_dir, "test.csv"), "w") as f:
+        f.write("name,value\nAlice,42\nBob,17\n")
+
+    # Register service
+    server, svc_info, instructions, service_url = await register_service(
+        server_url=SERVER_URL,
+        workspace=WORKSPACE,
+        token=TOKEN,
+        kernel=kernel,
+        data_dir=data_dir,
+        work_dir=work_dir,
+    )
+
+    assert svc_info is not None
+    assert service_url.startswith("https://")
+    assert "safe-colab-" in svc_info["id"]  # Random unlisted ID
+    assert "run_code" in instructions
+    assert "execute_command" in instructions
+    assert "upload_file" in instructions
+    assert "curl" in instructions
+    print(f"\nService URL: {service_url}")
+
+    # Connect as remote agent
+    from hypha_rpc import connect_to_server as connect
+    remote_server = await connect({
+        "server_url": SERVER_URL,
+        "workspace": WORKSPACE,
+        "token": TOKEN,
+    })
+    svc = await remote_server.get_service(svc_info["id"])
+
+    # Test 1: run_code - simple print
+    result = await svc.run_code("print('Hello from remote!')")
+    assert result["stdout"].strip() == "Hello from remote!"
+    assert result["error"] is None
+    print("Test 1 passed: run_code basic")
+
+    # Test 2: run_code - expression result
+    result = await svc.run_code("2 ** 10")
+    assert result["result"] == "1024"
+    print("Test 2 passed: run_code expression")
+
+    # Test 3: run_code - error handling
+    result = await svc.run_code("raise ValueError('test')")
+    assert result["error"]["ename"] == "ValueError"
+    print("Test 3 passed: run_code error")
+
+    # Test 4: run_code - state persistence
+    await svc.run_code("my_var = 'persistent_value'")
+    result = await svc.run_code("print(my_var)")
+    assert result["stdout"].strip() == "persistent_value"
+    print("Test 4 passed: state persistence")
+
+    # Test 5: execute_command - ls
+    result = await svc.execute_command(f"ls {data_dir}")
+    assert "test.csv" in result["stdout"]
+    assert result["returncode"] == 0
+    print("Test 5 passed: execute_command ls")
+
+    # Test 6: execute_command - pip
+    result = await svc.execute_command("python -c 'import json; print(json.dumps({\"ok\": True}))'")
+    assert result["returncode"] == 0
+    print("Test 6 passed: execute_command python")
+
+    # Test 7: run_code - read CSV, write output
+    code = f"""
+import csv
+with open("{data_dir}/test.csv") as f:
+    reader = csv.DictReader(f)
+    rows = list(reader)
+total = sum(int(r["value"]) for r in rows)
+print(f"Total: {{total}}")
+
+# Write results
+with open("{work_dir}/results.txt", "w") as f:
+    f.write(f"Total: {{total}}\\nRows: {{len(rows)}}\\n")
+print("Results saved")
+"""
+    result = await svc.run_code(code)
+    assert "Total: 59" in result["stdout"]
+    assert "Results saved" in result["stdout"]
+    print("Test 7 passed: CSV read + file write")
+
+    # Test 8: upload_file
+    result = await svc.upload_file(f"{work_dir}/results.txt")
+    assert "url" in result
+    assert result["url"].startswith("https://")
+    print(f"Test 8 passed: upload_file → {result['url'][:80]}...")
+
+    # Test 9: list_shared_files
+    files = await svc.list_shared_files()
+    # Should have at least the results.txt and audit_log.jsonl
+    print(f"Test 9 passed: list_shared_files → {len(files)} files")
+
+    # Test 10: get_docs
+    docs = await svc.get_docs()
+    assert "run_code" in docs
+    assert "execute_command" in docs
+    assert "upload_file" in docs
+    print(f"Test 10 passed: get_docs → {len(docs)} chars")
+
+    # Test 11: upload_file security - reject outside work_dir
+    result = await svc.upload_file("/etc/passwd")
+    assert "error" in result
+    assert "Access denied" in result["error"]
+    print("Test 11 passed: upload_file security check")
+
+    print("\nAll e2e tests passed!")

safe_colab_cli-0.1.0/tests/test_kernel.py

@@ -0,0 +1,78 @@
+"""Test the Jupyter kernel manager."""
+
+import pytest
+from safe_colab_cli.kernel import SandboxKernel
+
+
+@pytest.fixture
+async def kernel():
+    k = SandboxKernel()
+    await k.start()
+    yield k
+    await k.stop()
+
+
+@pytest.mark.asyncio
+async def test_kernel_start_stop():
+    """Test kernel can start and stop."""
+    k = SandboxKernel()
+    await k.start()
+    assert k._km is not None
+    assert k._kc is not None
+    await k.stop()
+
+
+@pytest.mark.asyncio
+async def test_kernel_execute_simple(kernel):
+    """Test simple code execution."""
+    result = await kernel.execute("print('hello world')")
+    assert result["stdout"].strip() == "hello world"
+    assert result["error"] is None
+
+
+@pytest.mark.asyncio
+async def test_kernel_execute_result(kernel):
+    """Test expression result capture."""
+    result = await kernel.execute("2 + 3")
+    assert result["result"] == "5"
+    assert result["error"] is None
+
+
+@pytest.mark.asyncio
+async def test_kernel_execute_error(kernel):
+    """Test error capture."""
+    result = await kernel.execute("1/0")
+    assert result["error"] is not None
+    assert result["error"]["ename"] == "ZeroDivisionError"
+
+
+@pytest.mark.asyncio
+async def test_kernel_execute_multiline(kernel):
+    """Test multiline code execution."""
+    code = """
+import os
+cwd = os.getcwd()
+print(f"cwd: {cwd}")
+"""
+    result = await kernel.execute(code)
+    assert "cwd:" in result["stdout"]
+    assert result["error"] is None
+
+
+@pytest.mark.asyncio
+async def test_kernel_execute_stderr(kernel):
+    """Test stderr capture."""
+    code = """
+import sys
+print("error msg", file=sys.stderr)
+"""
+    result = await kernel.execute(code)
+    assert "error msg" in result["stderr"]
+
+
+@pytest.mark.asyncio
+async def test_kernel_state_persistence(kernel):
+    """Test that variables persist across executions."""
+    await kernel.execute("x = 42")
+    result = await kernel.execute("print(x)")
+    assert result["stdout"].strip() == "42"