bilrost 0.1.0__tar.gz

bilrost-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+.venv/
+*.egg-info/
+dist/
+.pytest_cache/

bilrost-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Peleke Sengstacke
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bilrost-0.1.0/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: bilrost
+Version: 0.1.0
+Summary: Hardened Lima VM for running AI agents — overlay isolation, network containment, secrets management, and gated sync.
+Project-URL: Homepage, https://github.com/Peleke/openclaw-sandbox
+Project-URL: Documentation, https://peleke.github.io/openclaw-sandbox/
+Project-URL: Repository, https://github.com/Peleke/openclaw-sandbox
+Project-URL: Issues, https://github.com/Peleke/openclaw-sandbox/issues
+Project-URL: Changelog, https://github.com/Peleke/openclaw-sandbox/blob/main/CHANGELOG.md
+Author: Peleke Sengstacke
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,isolation,lima,sandbox,security,vm
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: System :: Emulators
+Requires-Python: >=3.11
+Requires-Dist: fastmcp<3,>=2
+Requires-Dist: jinja2<4,>=3.1
+Requires-Dist: pydantic<3,>=2
+Requires-Dist: rich<14,>=13
+Requires-Dist: tomli-w<2,>=1
+Requires-Dist: tomli<3,>=2; python_version < '3.11'
+Requires-Dist: typer<1,>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest<9,>=8; extra == 'dev'
+Requires-Dist: pyyaml<7,>=6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# bilrost
+
+**Hardened Lima VM for running AI agents** — overlay isolation, network containment, secrets management, and gated sync.
+
+## Install
+
+```bash
+# Via pipx (recommended)
+pipx install bilrost
+
+# Via uv
+uv tool install bilrost
+
+# Via pip
+pip install bilrost
+```
+
+## Usage
+
+```bash
+# Interactive setup
+bilrost init
+
+# Provision the VM (~5 min first run)
+bilrost up
+
+# Check status
+bilrost status
+
+# SSH into the VM
+bilrost ssh
+
+# Sync overlay changes to host (with secret scanning)
+bilrost sync
+
+# Stop / destroy
+bilrost down
+bilrost destroy
+```
+
+## MCP Server
+
+Agents can manage the sandbox programmatically via FastMCP:
+
+```json
+{
+  "mcpServers": {
+    "sandbox": {
+      "command": "bilrost-mcp"
+    }
+  }
+}
+```
+
+9 tools: `sandbox_status`, `sandbox_up`, `sandbox_down`, `sandbox_destroy`, `sandbox_exec`, `sandbox_validate`, `sandbox_ssh_info`, `sandbox_gateway_info`, `sandbox_agent_identity`.
+
+## What It Does
+
+- **OverlayFS isolation** — host code mounted read-only, all writes contained in VM overlay
+- **Network containment** — UFW firewall with explicit allowlist (HTTPS, DNS, Tailscale, NTP only)
+- **Secrets management** — three injection methods, `0600` perms, never in process lists
+- **Gated sync** — gitleaks scanning + path allowlist before changes reach your host
+- **Docker sandboxing** — per-session containers with configurable network isolation
+- **12 Ansible roles** — overlay, secrets, gateway, docker, firewall, sync-gate, gh-cli, buildlog, cadence, qortex, tailscale, and more
+
+## Requirements
+
+- macOS (Apple Silicon or Intel)
+- [Homebrew](https://brew.sh/)
+- ~10GB disk space
+
+Dependencies (Lima, Ansible, etc.) are installed automatically on first run.
+
+## Documentation
+
+Full docs: [peleke.github.io/openclaw-sandbox](https://peleke.github.io/openclaw-sandbox/)
+
+## License
+
+MIT

bilrost-0.1.0/README.md

@@ -0,0 +1,80 @@
+# bilrost
+
+**Hardened Lima VM for running AI agents** — overlay isolation, network containment, secrets management, and gated sync.
+
+## Install
+
+```bash
+# Via pipx (recommended)
+pipx install bilrost
+
+# Via uv
+uv tool install bilrost
+
+# Via pip
+pip install bilrost
+```
+
+## Usage
+
+```bash
+# Interactive setup
+bilrost init
+
+# Provision the VM (~5 min first run)
+bilrost up
+
+# Check status
+bilrost status
+
+# SSH into the VM
+bilrost ssh
+
+# Sync overlay changes to host (with secret scanning)
+bilrost sync
+
+# Stop / destroy
+bilrost down
+bilrost destroy
+```
+
+## MCP Server
+
+Agents can manage the sandbox programmatically via FastMCP:
+
+```json
+{
+  "mcpServers": {
+    "sandbox": {
+      "command": "bilrost-mcp"
+    }
+  }
+}
+```
+
+9 tools: `sandbox_status`, `sandbox_up`, `sandbox_down`, `sandbox_destroy`, `sandbox_exec`, `sandbox_validate`, `sandbox_ssh_info`, `sandbox_gateway_info`, `sandbox_agent_identity`.
+
+## What It Does
+
+- **OverlayFS isolation** — host code mounted read-only, all writes contained in VM overlay
+- **Network containment** — UFW firewall with explicit allowlist (HTTPS, DNS, Tailscale, NTP only)
+- **Secrets management** — three injection methods, `0600` perms, never in process lists
+- **Gated sync** — gitleaks scanning + path allowlist before changes reach your host
+- **Docker sandboxing** — per-session containers with configurable network isolation
+- **12 Ansible roles** — overlay, secrets, gateway, docker, firewall, sync-gate, gh-cli, buildlog, cadence, qortex, tailscale, and more
+
+## Requirements
+
+- macOS (Apple Silicon or Intel)
+- [Homebrew](https://brew.sh/)
+- ~10GB disk space
+
+Dependencies (Lima, Ansible, etc.) are installed automatically on first run.
+
+## Documentation
+
+Full docs: [peleke.github.io/openclaw-sandbox](https://peleke.github.io/openclaw-sandbox/)
+
+## License
+
+MIT

bilrost-0.1.0/pyproject.toml

@@ -0,0 +1,67 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "bilrost"
+version = "0.1.0"
+description = "Hardened Lima VM for running AI agents — overlay isolation, network containment, secrets management, and gated sync."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [{ name = "Peleke Sengstacke" }]
+keywords = ["sandbox", "ai-agents", "lima", "vm", "security", "isolation"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: MacOS",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Security",
+    "Topic :: Software Development :: Testing",
+    "Topic :: System :: Emulators",
+]
+dependencies = [
+    "typer>=0.12,<1",
+    "pydantic>=2,<3",
+    "tomli>=2,<3;python_version<'3.11'",
+    "tomli-w>=1,<2",
+    "rich>=13,<14",
+    "jinja2>=3.1,<4",
+    "fastmcp>=2,<3",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8,<9", "pyyaml>=6,<7"]
+
+[project.urls]
+Homepage = "https://github.com/Peleke/openclaw-sandbox"
+Documentation = "https://peleke.github.io/openclaw-sandbox/"
+Repository = "https://github.com/Peleke/openclaw-sandbox"
+Issues = "https://github.com/Peleke/openclaw-sandbox/issues"
+Changelog = "https://github.com/Peleke/openclaw-sandbox/blob/main/CHANGELOG.md"
+
+[project.scripts]
+bilrost = "sandbox_cli.app:app"
+bilrost-mcp = "sandbox_cli.mcp_server:main"
+# Keep legacy entry points for backward compat
+sandbox = "sandbox_cli.app:app"
+sandbox-mcp = "sandbox_cli.mcp_server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sandbox_cli"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/sandbox_cli/",
+    "README.md",
+    "LICENSE",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

bilrost-0.1.0/src/sandbox_cli/_capture.py

@@ -0,0 +1,69 @@
+"""Output capture utilities for MCP stdio transport safety.
+
+Rich console output and subprocess stdout must not leak into the MCP
+stdio channel.  This module provides helpers to capture or suppress
+output so tool implementations stay transport-safe.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import io
+import os
+import sys
+from dataclasses import dataclass
+from typing import Callable
+
+from rich.console import Console
+
+
+@dataclass
+class CapturedExec:
+    """Result of a captured subprocess execution."""
+
+    stdout: str
+    stderr: str
+    exit_code: int
+
+
+def make_capture_console() -> Console:
+    """Return a Rich console that writes to an in-memory buffer.
+
+    The caller can retrieve the output via ``console.file.getvalue()``.
+    """
+    return Console(file=io.StringIO(), force_terminal=False)
+
+
+@contextlib.contextmanager
+def suppress_stdout():
+    """Context manager that redirects ``sys.stdout`` to ``os.devnull``.
+
+    Useful when calling functions that may print directly (not via Rich)
+    or when ``subprocess.run`` inherits stdout.
+    """
+    devnull = open(os.devnull, "w")
+    old_stdout = sys.stdout
+    try:
+        sys.stdout = devnull
+        yield
+    finally:
+        sys.stdout = old_stdout
+        devnull.close()
+
+
+def run_captured(fn: Callable[..., object], *args: object, **kwargs: object) -> str:
+    """Call *fn* with a capture console and return the output text.
+
+    The function must accept a ``console`` keyword argument (matching
+    the pattern used by ``print_post_bootstrap`` and ``print_status_report``).
+    """
+    cap = make_capture_console()
+    fn(*args, console=cap, **kwargs)
+    return cap.file.getvalue()
+
+
+def _truncate(text: str, max_chars: int = 50_000) -> str:
+    """Truncate *text* to *max_chars*, appending a marker if clipped."""
+    if len(text) <= max_chars:
+        return text
+    return text[:max_chars] + "\n\n[output truncated]"

bilrost-0.1.0/src/sandbox_cli/ansible_runner.py

@@ -0,0 +1,96 @@
+"""Ansible inventory builder and playbook invocation."""
+
+from __future__ import annotations
+
+import getpass
+import os
+import subprocess
+import tempfile
+from pathlib import Path
+
+from .lima_config import secrets_filename
+from .lima_manager import SSHDetails
+from .models import SandboxProfile
+
+
+def build_inventory(vm_name: str, ssh: SSHDetails) -> str:
+    """Return an INI-format Ansible inventory string."""
+    return (
+        "[sandbox]\n"
+        f"{vm_name} "
+        f"ansible_host={ssh.host} "
+        f"ansible_port={ssh.port} "
+        f"ansible_user={ssh.user} "
+        f"ansible_ssh_private_key_file={ssh.key_path} "
+        "ansible_ssh_common_args='-o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null'\n"
+    )
+
+
+def build_extra_vars(profile: SandboxProfile) -> list[str]:
+    """Build the ``-e key=value`` argument list for ``ansible-playbook``.
+
+    Matches the exact set of variables that ``bootstrap.sh`` passes.
+    """
+    sec_fname = secrets_filename(profile)
+    tenant = getpass.getuser()
+
+    # Conditional mount paths — empty string when not configured
+    agent_mount = "/mnt/openclaw-agents" if profile.mounts.agent_data else ""
+    buildlog_mount = "/mnt/buildlog-data" if profile.mounts.buildlog_data else ""
+
+    pairs: list[tuple[str, str]] = [
+        ("tenant_name", tenant),
+        ("provision_path", "/mnt/provision"),
+        ("openclaw_path", "/mnt/openclaw"),
+        ("obsidian_path", "/mnt/obsidian"),
+        ("secrets_filename", sec_fname),
+        ("overlay_yolo_mode", str(profile.mode.yolo).lower()),
+        ("overlay_yolo_unsafe", str(profile.mode.yolo_unsafe).lower()),
+        ("docker_enabled", str(not profile.mode.no_docker).lower()),
+        ("agent_data_mount", agent_mount),
+        ("buildlog_data_mount", buildlog_mount),
+        ("memgraph_enabled", str(profile.mode.memgraph).lower()),
+    ]
+
+    argv: list[str] = []
+    for key, value in pairs:
+        argv.extend(["-e", f"{key}={value}"])
+
+    # User-supplied extra vars
+    for key, value in profile.extra_vars.items():
+        argv.extend(["-e", f"{key}={value}"])
+
+    return argv
+
+
+def run_playbook(
+    profile: SandboxProfile,
+    ssh: SSHDetails,
+    bootstrap_dir: Path,
+    *,
+    vm_name: str = "openclaw-sandbox",
+) -> int:
+    """Write a temp inventory, run ``ansible-playbook``, clean up.
+
+    Returns the ansible-playbook exit code.
+    """
+    inventory_text = build_inventory(vm_name, ssh)
+    playbook = bootstrap_dir / "ansible" / "playbook.yml"
+
+    fd, inv_path = tempfile.mkstemp(prefix="sandbox-inv-", suffix=".ini")
+    try:
+        with os.fdopen(fd, "w") as f:
+            f.write(inventory_text)
+
+        cmd = [
+            "ansible-playbook",
+            "-i",
+            inv_path,
+            str(playbook),
+        ] + build_extra_vars(profile)
+
+        env = {**os.environ, "ANSIBLE_HOST_KEY_CHECKING": "False"}
+        result = subprocess.run(cmd, env=env)
+        return result.returncode
+    finally:
+        Path(inv_path).unlink(missing_ok=True)

bilrost-0.1.0/src/sandbox_cli/app.py

@@ -0,0 +1,194 @@
+"""OpenClaw Sandbox CLI — Typer app and subcommand definitions."""
+
+from __future__ import annotations
+
+from typing import Annotated, Optional
+
+import typer
+from rich.console import Console
+
+from .bootstrap import find_bootstrap_dir, run_script
+from .dashboard import run_dashboard_sync
+from .lima_manager import LimaManager
+from .models import SandboxProfile
+from .orchestrator import orchestrate_up
+from .profile import init_wizard, load_profile
+from .reporting import print_status_report
+from .validation import validate_profile
+
+app = typer.Typer(
+    name="sandbox",
+    help="OpenClaw Sandbox — provision once, run forever.",
+    no_args_is_help=True,
+)
+console = Console()
+
+_ONBOARD_CMD = (
+    'cd "$(if mountpoint -q /workspace 2>/dev/null; '
+    "then echo /workspace; else echo /mnt/openclaw; fi)\" "
+    "&& node dist/index.js onboard"
+)
+
+
+# ── helpers ──────────────────────────────────────────────────────────────
+
+
+def _load_and_validate(*, strict: bool = True) -> SandboxProfile:
+    """Load the profile and run validation. Exit on errors if strict."""
+    profile = load_profile()
+    result = validate_profile(profile)
+    for w in result.warnings:
+        console.print(f"[yellow]warning:[/yellow] {w}")
+    if not result.ok:
+        for e in result.errors:
+            console.print(f"[red]error:[/red] {e}")
+        if strict:
+            raise typer.Exit(1)
+    return profile
+
+
+# ── subcommands ──────────────────────────────────────────────────────────
+
+
+@app.command()
+def init() -> None:
+    """Interactive wizard to create or update your sandbox profile."""
+    init_wizard()
+
+
+@app.command()
+def up(
+    fresh: Annotated[
+        bool,
+        typer.Option("--fresh", help="Destroy existing VM first, then reprovision."),
+    ] = False,
+) -> None:
+    """Provision (or reprovision) the sandbox VM."""
+    profile = _load_and_validate()
+    bootstrap_dir = find_bootstrap_dir(profile)
+    lima = LimaManager()
+    if fresh:
+        console.print("[bold]Destroying existing VM before reprovisioning...[/bold]")
+        lima.delete()
+    rc = orchestrate_up(profile, bootstrap_dir, lima=lima)
+    raise typer.Exit(rc)
+
+
+@app.command()
+def down() -> None:
+    """Stop the sandbox VM (force kill)."""
+    _load_and_validate(strict=False)
+    lima = LimaManager()
+    lima.stop(force=True)
+    console.print("VM stopped.")
+
+
+@app.command()
+def destroy(
+    force: Annotated[
+        bool,
+        typer.Option("-f", "--force", help="Skip confirmation prompt."),
+    ] = False,
+) -> None:
+    """Delete the sandbox VM entirely."""
+    if not force:
+        confirm = typer.confirm("This will permanently delete the VM. Continue?")
+        if not confirm:
+            raise typer.Abort()
+    _load_and_validate(strict=False)
+    lima = LimaManager()
+    lima.delete()
+    console.print("VM deleted.")
+
+
+@app.command()
+def status() -> None:
+    """Show VM state and profile summary."""
+    profile = _load_and_validate(strict=False)
+    print_status_report(profile, console)
+
+
+@app.command()
+def ssh() -> None:
+    """SSH into the sandbox VM (replaces process for TTY)."""
+    _load_and_validate(strict=False)
+    lima = LimaManager()
+    lima.shell()
+
+
+@app.command()
+def onboard() -> None:
+    """Run the onboarding wizard inside the VM (replaces process for TTY)."""
+    _load_and_validate(strict=False)
+    lima = LimaManager()
+    lima.shell_exec(_ONBOARD_CMD)
+
+
+@app.command()
+def sync(
+    dry_run: Annotated[
+        bool,
+        typer.Option("--dry-run", help="Preview changes without applying."),
+    ] = False,
+) -> None:
+    """Sync overlay changes from VM to host."""
+    profile = _load_and_validate(strict=False)
+    flags = []
+    if dry_run:
+        flags.append("--dry-run")
+    rc = run_script(profile, "sync-gate.sh", extra_flags=flags)
+    raise typer.Exit(rc)
+
+
+# ── dashboard sub-app ────────────────────────────────────────────────────
+
+dashboard_app = typer.Typer(
+    name="dashboard",
+    help="Gateway dashboard and GitHub-to-Obsidian sync.",
+    invoke_without_command=True,
+)
+app.add_typer(dashboard_app)
+
+
+@dashboard_app.callback(invoke_without_command=True)
+def dashboard_open(
+    ctx: typer.Context,
+    page: Annotated[
+        Optional[str],
+        typer.Option("--page", "-p", help="Dashboard page: control, green, learning"),
+    ] = None,
+) -> None:
+    """Open the OpenClaw gateway dashboard."""
+    if ctx.invoked_subcommand is not None:
+        return
+    profile = _load_and_validate(strict=False)
+    flags = []
+    if page:
+        flags.append(page)
+    rc = run_script(profile, "dashboard.sh", extra_flags=flags)
+    raise typer.Exit(rc)
+
+
+@dashboard_app.command("sync")
+def dashboard_sync(
+    dry_run: Annotated[
+        bool,
+        typer.Option("--dry-run", help="Preview without writing files."),
+    ] = False,
+) -> None:
+    """Sync GitHub issues to Obsidian kanban boards."""
+    profile = _load_and_validate(strict=False)
+    try:
+        result = run_dashboard_sync(profile, dry_run=dry_run)
+    except FileNotFoundError as exc:
+        console.print(f"[red]error:[/red] {exc}")
+        raise typer.Exit(1) from None
+
+    if result.stdout:
+        console.print(result.stdout.rstrip())
+    if result.returncode != 0:
+        if result.stderr:
+            console.print(f"[yellow]{result.stderr.rstrip()}[/yellow]")
+        console.print(f"[red]Sync failed (exit {result.returncode}).[/red]")
+        raise typer.Exit(result.returncode)
+    console.print("[green]Dashboard sync complete.[/green]")