slopbox-env 0.1.0__tar.gz

slopbox_env-0.1.0/PKG-INFO

@@ -0,0 +1,36 @@
+Metadata-Version: 2.3
+Name: slopbox-env
+Version: 0.1.0
+Summary: A secure-ish environment for running AI agents.
+Requires-Dist: click>=8.4.2
+Requires-Dist: pydantic>=2.13.4
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# Slopbox
+**A secure-ish environment for running AI agents.**
+
+The goal of this project is to make it very easy to _set up
+an isolated runtime_ (container or virtual machine) for an AI agent.
+
+What you can expect:
+* intuitive configuration with sane defaults
+* principle of least privilege
+   * include only the packages that are neccessary for the agent to operate
+   * restrict agent's network access through a customizable proxy
+   * grant access only to a subset of directories
+* just works™
+
+**DISCLAIMER**: this project is on a very early stage of development -- things will break, things will change.
+
+## Requirements
+- Nix
+- Podman or Docker
+   - rootless mode required
+   - guide for docker on NixOS: https://wiki.nixos.org/wiki/Docker#Rootless_Docker
+
+## Docs
+No documentation is available at this point.
+
+## What's next
+See the list of [planned features](/issues?q=is%3Aissue+state%3Aopen+label%3Aenhancement+author%3AjkbSeven)

slopbox_env-0.1.0/README.md

@@ -0,0 +1,27 @@
+# Slopbox
+**A secure-ish environment for running AI agents.**
+
+The goal of this project is to make it very easy to _set up
+an isolated runtime_ (container or virtual machine) for an AI agent.
+
+What you can expect:
+* intuitive configuration with sane defaults
+* principle of least privilege
+   * include only the packages that are neccessary for the agent to operate
+   * restrict agent's network access through a customizable proxy
+   * grant access only to a subset of directories
+* just works™
+
+**DISCLAIMER**: this project is on a very early stage of development -- things will break, things will change.
+
+## Requirements
+- Nix
+- Podman or Docker
+   - rootless mode required
+   - guide for docker on NixOS: https://wiki.nixos.org/wiki/Docker#Rootless_Docker
+
+## Docs
+No documentation is available at this point.
+
+## What's next
+See the list of [planned features](/issues?q=is%3Aissue+state%3Aopen+label%3Aenhancement+author%3AjkbSeven)

slopbox_env-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[project]
+name = "slopbox-env"
+version = "0.1.0"
+description = "A secure-ish environment for running AI agents."
+readme = "README.md"
+requires-python = ">=3.14"
+dependencies = [
+    "click>=8.4.2",
+    "pydantic>=2.13.4",
+]
+
+[project.scripts]
+slopbox = "slopbox.main:main"
+
+[dependency-groups]
+dev = ["pytest>=9.1.1"]
+
+[build-system]
+requires = ["uv_build>=0.11.22,<0.12"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "slopbox"
+
+[tool.ruff]
+line-length = 88
+indent-width = 4
+target-version = "py314"
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "UP",
+    "B",
+    "SIM",
+]

slopbox_env-0.1.0/pyproject.toml.orig

@@ -0,0 +1,40 @@
+[project]
+name = "slopbox-env"
+version = "0.1.0"
+description = "A secure-ish environment for running AI agents."
+readme = "README.md"
+requires-python = ">=3.14"
+dependencies = [
+    "click>=8.4.2",
+    "pydantic>=2.13.4",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.22,<0.12"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "slopbox"
+
+[project.scripts]
+slopbox = "slopbox.main:main"
+
+[tool.ruff]
+line-length = 88
+indent-width = 4
+target-version = "py314"
+
+[tool.ruff.lint]
+select = [
+    "E",    # pycodestyle
+    "F",    # pyflakes
+    "I",    # isort
+    "UP",   # pyupgrade
+    "B",    # flake8 bugbear
+    "SIM",  # flake8 simplify
+]

slopbox_env-0.1.0/src/slopbox/config.py

@@ -0,0 +1,91 @@
+"""
+Configuration for slopbox as a CLI tool,
+not for runtime container or vm configuration -- for that use environment module
+"""
+
+import tomllib
+import typing
+from pathlib import Path
+
+import pydantic
+
+MAX_CONFIG_BYTES = 4096
+DEFAULT_CONFIG_PATH = Path.home() / ".config" / "slopbox" / "config.toml"
+
+
+class ConfigError(Exception):
+    pass
+
+
+class SlopboxPaths(typing.NamedTuple):
+    env: Path
+    lock: Path
+
+
+class Config(pydantic.BaseModel):
+    slopbox_env_dir: Path = pydantic.Field(
+        default_factory=lambda: Path.home() / ".config" / "slopbox"
+    )
+
+    model_config = pydantic.ConfigDict(
+        extra="forbid",
+        validate_assignment=True,
+    )
+
+    @property
+    def slopbox_paths(self) -> SlopboxPaths:
+        return SlopboxPaths(
+            env=self.slopbox_env_dir / "slopbox.nix",
+            lock=self.slopbox_env_dir / "slopbox.lock",
+        )
+
+    @pydantic.field_validator("slopbox_env_dir", mode="after")
+    @classmethod
+    def __expand_slopbox_env_dir(cls, v: Path) -> Path:
+        return v.expanduser().resolve()
+
+    @classmethod
+    def load(cls, config_path: Path | None = None) -> Config:
+        if config_path is None:
+            config_path = DEFAULT_CONFIG_PATH
+
+        if not config_path.is_file():
+            return cls()
+
+        filesize = config_path.lstat().st_size
+
+        if filesize > MAX_CONFIG_BYTES:
+            raise ConfigError(
+                f"config file {config_path} has size of {filesize} bytes, "
+                f"maximum allowed size is {MAX_CONFIG_BYTES} bytes"
+            )
+
+        with config_path.open(mode="rb") as fp:
+            try:
+                toml_data = tomllib.load(fp)
+            except tomllib.TOMLDecodeError as err:
+                raise ConfigError(f"failed to load TOML file: {err}") from err
+
+        try:
+            c = cls.model_validate(toml_data)
+
+        except pydantic.ValidationError as err:
+            errors = err.errors(include_url=False)
+            errors_pretty = map(
+                lambda e: str({"field": e["loc"][0], "error": e["msg"]}), errors
+            )
+            raise ConfigError(
+                f"invalid configuration:\n{'\n'.join(errors_pretty)}"
+            ) from err
+
+        except Exception as err:
+            raise ConfigError(f"invalid configuration: {err}") from err
+
+        return c
+
+    def pretty_print(self) -> str:
+        # assumes flat config struct
+        return "\n".join([f"{k} = {v}" for k, v in self])
+
+
+load = Config.load

slopbox_env-0.1.0/src/slopbox/const.py

@@ -0,0 +1,10 @@
+from pathlib import Path
+
+VERSION = "0.1.0"
+
+PKG_ROOT = Path(__file__).parent.absolute()
+
+NIX_ROOT = PKG_ROOT / "nix"
+NIX_LIB_PATH = NIX_ROOT / "lib"
+
+NIXPKGS_FETCH_URL = "github:nixos/nixpkgs/nixos-unstable"

slopbox_env-0.1.0/src/slopbox/container_engine.py

@@ -0,0 +1,75 @@
+import shutil
+import subprocess
+from typing import Protocol
+
+
+class ContainerEngineError(Exception):
+    pass
+
+
+class ContainerEngine(Protocol):
+    name: str
+
+    @classmethod
+    def is_available(cls) -> bool: ...
+
+    @classmethod
+    def is_rootless(cls) -> bool: ...
+
+
+class Docker:
+    name = "docker"
+
+    @classmethod
+    def is_available(cls) -> bool:
+        return shutil.which("docker") is not None
+
+    @classmethod
+    def is_rootless(cls) -> bool:
+        if not cls.is_available():
+            raise ContainerEngineError("docker is not installed")
+
+        ret = subprocess.run(
+            ["docker", "info", "--format", "{{ .SecurityOptions }}"],
+            capture_output=True,
+        )
+
+        if ret.returncode != 0:
+            raise ContainerEngineError(
+                "error while checking if docker is rootless: "
+                "command 'docker info' failed: "
+                f"{ret.stderr.decode(encoding='utf-8')}"
+            )
+
+        clean = ret.stdout.decode(encoding="utf-8").strip("[]")
+
+        return "name=rootless" in clean
+
+
+class Podman:
+    name = "podman"
+
+    @classmethod
+    def is_available(cls) -> bool:
+        return shutil.which("podman") is not None
+
+    @classmethod
+    def is_rootless(cls) -> bool:
+        if not cls.is_available():
+            raise ContainerEngineError("podman is not installed")
+
+        # TODO: check if having non-rootless podman is even possible
+        return True
+
+
+def get_container_engine() -> ContainerEngine:
+    # in case user has both, we prefer podman
+    if Podman.is_available():
+        return Podman()
+
+    if Docker.is_available():
+        return Docker()
+
+    raise ContainerEngineError(
+        "neither podman nor docker is installed (not found in $PATH)"
+    )

slopbox_env-0.1.0/src/slopbox/environment.py

@@ -0,0 +1,24 @@
+EXAMPLE_ENV_CONFIG = """{
+  pkgs,
+  ...
+}:
+{
+  default = {
+    agent = pkgs.opencode;
+    workspace = "/workspace";
+  };
+
+  profiles = {
+    default = {
+      pkgs = [
+        pkgs.python314
+        pkgs.uv
+      ];
+
+      runHook = "echo 'Hello, world!'";
+    };
+  };
+
+  schemaVersion = 1;
+}
+"""

slopbox_env-0.1.0/src/slopbox/main.py

@@ -0,0 +1,341 @@
+import json
+import subprocess
+from pathlib import Path
+
+import click
+
+from slopbox import config, const, container_engine, environment
+from slopbox.nix import Nix, NixError, NixFetchTreeResult
+
+
+class fmt:
+    esc = "\x1b"
+    checkmark = "\u2713"
+
+    @staticmethod
+    def red(msg: str, **kwargs) -> str:
+        return click.style(msg, fg="red", **kwargs)
+
+    @staticmethod
+    def green(msg: str, **kwargs) -> str:
+        return click.style(msg, fg="green", **kwargs)
+
+    @staticmethod
+    def up(count: int, *, goto_beg: bool) -> str:
+        return f"{fmt.esc}[{count}A" + ("\r" if goto_beg else "")
+
+    @staticmethod
+    def clear_line() -> str:
+        return f"{fmt.esc}[2K"
+
+
+def _init_config_dir(config_dir: Path):
+    try:
+        config_dir.mkdir(mode=0o700, parents=True, exist_ok=True)
+    except (OSError, FileNotFoundError) as err:
+        raise click.ClickException(
+            f"unable to create or read the config directory ({config_dir}): {err}"
+        ) from err
+
+
+def _err_if_unhealthy() -> None:
+    if not Nix.is_available():
+        raise click.ClickException(
+            "You have to install Nix prior to using slopbox; "
+            "Nix main page: https://nixos.org/"
+        )
+
+    try:
+        cengine = container_engine.get_container_engine()
+
+    except container_engine.ContainerEngineError as err:
+        raise click.ClickException(
+            f"unable to resolve container engine: {err}"
+        ) from err
+
+    if not cengine.is_rootless():
+        raise click.ClickException(
+            f"{cengine.name} is not running in rootless mode, "
+            "this has security implications and slopbox cannot proceed"
+        )
+
+
+@click.group()
+@click.version_option(version=const.VERSION, message="%(version)s")
+@click.option(
+    "--config",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    help="Path to a config file (.toml)",
+)
+@click.pass_context
+def cli(ctx: click.Context, config: Path | None):
+    """secure-ish environment for running AI agents"""
+    ctx.ensure_object(dict)
+    ctx.obj["config"] = config
+
+
+@cli.command("health")
+def cli_health():
+    """validate runtime health"""
+    nix_status: str
+    if not Nix.is_available():
+        nix_status = f"Nix: {fmt.red('NOT INSTALLED', bold=True)}"
+    else:
+        nix_status = f"Nix: {fmt.green('OK', bold=True)}"
+    click.echo(nix_status)
+
+    cengine_status: str
+    try:
+        cengine = container_engine.get_container_engine()
+    except container_engine.ContainerEngineError as err:
+        cengine_status = (
+            f"Container engine: {fmt.red('MISSING', bold=True)} (err: {err})"
+        )
+    else:
+        rootless_status = (
+            "(rootless)" if cengine.is_rootless() else fmt.red("(non-rootless)")
+        )
+        cengine_status = (
+            f"Container engine: {fmt.green(cengine.name, bold=True)} {rootless_status}"
+        )
+    click.echo(cengine_status)
+
+
+@cli.command("build")
+@click.option("--profile", "-p", default="default")
+@click.option(
+    "--runtime",
+    "-r",
+    default="container",
+    type=click.Choice(["container", "vm"]),
+)
+@click.pass_context
+def cli_build(ctx: click.Context, profile: str, runtime: str):
+    """build profile"""
+    if runtime != "container":
+        raise click.ClickException(f"'{runtime}' runtime is not supported yet")
+
+    _err_if_unhealthy()
+
+    c = config.load(ctx.obj["config"])
+
+    env_file, lock_file = c.slopbox_paths
+
+    if not lock_file.exists():
+        raise click.ClickException(
+            f"You haven't locked slopbox dependencies: {lock_file} does not exist. "
+            "Run `slopbox init` first, then rerun this command"
+        )
+
+    if not env_file.exists():
+        raise click.ClickException(
+            "You haven't created a slopbox environment: "
+            f"{env_file} does not exist. "
+            "Run `slopbox init`, adjust the environment to your needs, "
+            "then rerun this command"
+        )
+
+    lock = NixFetchTreeResult.model_validate_json(lock_file.read_text(encoding="utf-8"))
+    nixpkgs_url = lock.fetch_tree_url()
+
+    click.echo(f"Building profile '{profile}':")
+
+    try:
+        profile_data = Nix.profile_data(str(env_file), nixpkgs_url, profile)
+    except NixError as err:
+        raise click.ClickException(
+            f"failed to evaluate profile with nix: {err}"
+        ) from err
+
+    engine = container_engine.get_container_engine().name
+
+    def _build(component: str):
+        click.echo(f"-> building {component}...")
+        try:
+            loader_path = Nix.build_container_loader(
+                env_path=str(env_file),
+                nixpkgs_url=nixpkgs_url,
+                profile=profile,
+                engine=engine,
+                component=component,
+            )
+        except NixError as err:
+            raise click.ClickException(f"build failed: {err}") from err
+
+        result = subprocess.run(f"{loader_path}/bin/loader", capture_output=True)
+
+        if result.returncode != 0:
+            raise click.ClickException(
+                "failed to load the container image: "
+                + result.stderr.decode(encoding="utf-8")
+            )
+
+        click.echo(
+            fmt.up(1, goto_beg=True)
+            + fmt.clear_line()
+            + fmt.green(fmt.checkmark)
+            + f" built {component} ({profile_data['containers'][component]['image']})"
+        )
+
+    _build("runtime")
+    if profile_data["profile"]["proxy"]["enable"] is True:
+        _build("proxy")
+
+
+@cli.command("init")
+@click.pass_context
+def cli_init(ctx: click.Context):
+    """initialize slopbox environment (user-wide)"""
+    if not Nix.is_available():
+        raise click.ClickException(
+            "You have to install Nix prior to using slopbox; "
+            "Nix main page: https://nixos.org/"
+        )
+
+    c = config.load(ctx.obj["config"])
+
+    _init_config_dir(c.slopbox_env_dir)
+
+    env_file, lock_file = c.slopbox_paths
+
+    if not lock_file.exists():
+        try:
+            nixpkgs_tree = Nix.fetch_tree(const.NIXPKGS_FETCH_URL)
+        except NixError as err:
+            raise click.ClickException(
+                f"failed to fetch and pin nixpkgs revision: {err}"
+            ) from err
+
+        lock_file.write_text(
+            nixpkgs_tree.model_dump_json(indent=2, by_alias=True),
+            encoding="utf-8",
+        )
+
+    if not env_file.exists():
+        env_file.write_text(environment.EXAMPLE_ENV_CONFIG, encoding="utf-8")
+
+
+@cli.command("profile")
+@click.argument("profile", default="default")
+@click.pass_context
+def cli_profile(ctx: click.Context, profile: str):
+    """print profile data and build metadata"""
+    _err_if_unhealthy()
+
+    c = config.load(ctx.obj["config"])
+
+    env_file, lock_file = c.slopbox_paths
+
+    if not lock_file.exists():
+        raise click.ClickException(
+            f"You haven't locked slopbox dependencies: {lock_file} does not exist. "
+            "Run `slopbox init` first, then rerun this command"
+        )
+
+    if not env_file.exists():
+        raise click.ClickException(
+            "You haven't created a slopbox environment: "
+            f"{env_file} does not exist. "
+            "Run `slopbox init`, adjust the environment to your needs, "
+            "then rerun this command"
+        )
+
+    lock = NixFetchTreeResult.model_validate_json(lock_file.read_text(encoding="utf-8"))
+    try:
+        profile_data = Nix.profile_data(str(env_file), lock.fetch_tree_url(), profile)
+    except NixError as err:
+        raise click.ClickException(
+            f"failed to evaluate profile with nix: {err}"
+        ) from err
+
+    click.echo(json.dumps(profile_data, indent=2))
+
+
+@cli.command("run")
+@click.option("--profile", "-p", default="default")
+@click.option(
+    "--runtime",
+    "-r",
+    default="container",
+    type=click.Choice(["container", "vm"]),
+)
+@click.pass_context
+def cli_run(ctx: click.Context, profile: str, runtime: str):
+    """run profile"""
+    if runtime != "container":
+        raise click.ClickException(f"'{runtime}' runtime is not supported yet")
+
+    _err_if_unhealthy()
+
+    c = config.load(ctx.obj["config"])
+    env_file, lock_file = c.slopbox_paths
+
+    if not lock_file.exists():
+        raise click.ClickException(
+            f"You haven't locked slopbox dependencies: {lock_file} does not exist. "
+            "Run `slopbox init` first, then rerun this command"
+        )
+
+    if not env_file.exists():
+        raise click.ClickException(
+            "You haven't created a slopbox environment: "
+            f"{env_file} does not exist. "
+            "Run `slopbox init`, adjust the environment to your needs, "
+            "then rerun this command"
+        )
+
+    lock = NixFetchTreeResult.model_validate_json(lock_file.read_text(encoding="utf-8"))
+    nixpkgs_url = lock.fetch_tree_url()
+    engine = container_engine.get_container_engine().name
+
+    runner_path = Nix.build_container_runner(
+        str(env_file), nixpkgs_url, profile, engine
+    )
+
+    result = subprocess.run(f"{runner_path}/bin/run")
+
+    if result.returncode != 0:
+        raise click.ClickException(
+            f"error during runtime, please see the {engine} logs above"
+        )
+
+
+@cli.group("config")
+def cli_config():
+    """manage tool configuration (slopbox CLI)"""
+
+
+@cli_config.command("show")
+@click.pass_context
+def cli_config_show(ctx: click.Context):
+    """show resolved tool configuration"""
+    try:
+        c = config.load(ctx.obj["config"])
+
+    except config.ConfigError as err:
+        raise click.ClickException(f"error while loading tool config: {err}") from err
+
+    click.echo(c.pretty_print())
+
+
+@cli_config.command("edit")
+@click.pass_context
+def cli_config_edit(ctx: click.Context):
+    """edit tool configuration in your text editor ($EDITOR)"""
+    p = ctx.obj["config"] or config.DEFAULT_CONFIG_PATH
+    p.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+
+    if p.exists() and not p.is_file():
+        raise click.ClickException(
+            f"config path exists but does not point to a file: {p}"
+        )
+
+    click.edit(filename=str(p))
+
+
+def main():
+    cli()
+
+
+if __name__ == "__main__":
+    main()

slopbox_env-0.1.0/src/slopbox/nix/build-container-loader.nix

@@ -0,0 +1,12 @@
+{
+  nixpkgsUrl,
+  slopboxEnvPath,
+  profile,
+  engine,
+  component,
+}:
+let
+  lib = import ./lib;
+  cfg = (lib.config.eval { inherit nixpkgsUrl slopboxEnvPath; }).config;
+in
+cfg.profiles.${profile}.build.${component}.container-loader.${engine}