agent-leash 0.3.0__tar.gz

agent_leash-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v8.1.0
+      - name: Install frontend deps
+        run: npm --prefix frontend ci
+      - uses: pre-commit/action@v3.0.1
+        with:
+          extra_args: --all-files

agent_leash-0.3.0/.github/workflows/release.yml

@@ -0,0 +1,75 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v[0-9]+.[0-9]+.[0-9]+'
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - name: Check tag matches pyproject.toml version
+        run: |
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          PKG_VERSION=$(uv version --short)
+          if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then
+            echo "Tag $GITHUB_REF_NAME does not match pyproject.toml version $PKG_VERSION"
+            exit 1
+          fi
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v8.1.0
+      - uses: pre-commit/action@v3.0.1
+        with:
+          extra_args: --all-files
+  build:
+    needs: [validate, lint]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - name: Install frontend deps
+        run: npm --prefix frontend ci
+      - name: Build distribution
+        run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    needs: [build]
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+
+  github-release:
+    needs: [publish-pypi]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: |
+            dist/*
+          generate_release_notes: true

agent_leash-0.3.0/.gitignore

@@ -0,0 +1,5 @@
+**/*.swp
+**/node_modules/**
+**/__pycache__/**
+frontend/tsconfig.tsbuildinfo
+.venv/

agent_leash-0.3.0/.pre-commit-config.yaml

@@ -0,0 +1,55 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: check-added-large-files
+        args: [--maxkb=1000]
+      - id: debug-statements
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.4.2
+    hooks:
+      - id: codespell
+        name: Spell check source files
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.14
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: local
+    hooks:
+      - id: pyright
+        name: Type checking for python
+        entry: uv run --frozen pyright
+        language: system
+        types: [python]
+        pass_filenames: false
+      - id: vue-tsc
+        name: TypeScript type check (frontend)
+        entry: npm --prefix frontend run typecheck
+        language: system
+        files: ^frontend/src/.*\.(ts|vue)$
+        pass_filenames: false
+      - id: eslint-frontend
+        name: ESLint (frontend)
+        entry: npm --prefix frontend run lint
+        language: system
+        files: ^frontend/src/.*\.(ts|vue)$
+        pass_filenames: false
+      - id: licensecheck
+        name: License compatibility
+        entry: uv run --frozen licensecheck
+        language: system
+        pass_filenames: false
+        stages: [pre-push]
+      - id: uv-audit
+        name: Vulnerability scan (uv audit)
+        entry: uv audit
+        language: system
+        pass_filenames: false
+        stages: [pre-push]

agent_leash-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,120 @@
+# Contributing
+
+## System requirements
+
+| Tool | Purpose | Install |
+|------|---------|---------|
+| `bwrap` | filesystem isolation | `dnf install bubblewrap` / `apt install bubblewrap` |
+| `xdg-dbus-proxy` | portal socket for xdg-open | `dnf install xdg-dbus-proxy` / `apt install xdg-dbus-proxy` |
+| Python ≥ 3.11 | backend | system or pyenv |
+| Node ≥ 18 + npm | frontend build | system or nvm |
+
+`mitmproxy` is a Python dependency — no separate install needed.
+
+## First-time setup
+
+```sh
+git clone <repo> aleash
+cd aleash
+
+# Python env — uv creates .venv, downloads Python 3.12 (pinned in .python-version),
+# and installs all deps. The frontend build is skipped for editable installs.
+uv sync
+
+# Frontend deps + initial build (one-time)
+cd frontend
+npm install       # generates package-lock.json if missing
+npm run build     # outputs to src/aleash/static/
+cd ..
+```
+
+## Running in dev mode
+
+Two terminals needed.
+
+**Terminal 1 — daemon (foreground so you see logs):**
+
+```sh
+uv run aleash start --foreground
+# → Sandbox UI available on http://localhost:7612/
+```
+
+**Terminal 2 — run an agent:**
+
+```sh
+cd /some/project
+uv run --project /path/to/aleash aleash claude
+```
+
+Open http://localhost:7612/ to see the UI.
+
+## Frontend iteration
+
+```sh
+make frontend
+# → http://localhost:5173/
+```
+
+Vite serves the UI with hot-reload. Edits to `frontend/src/` reflect instantly in the browser.
+Proxies `/api` and `/ws` to the daemon — requires `uv run aleash start --foreground` running first.
+
+## Project layout
+
+```
+src/aleash/
+  cli.py          # Click commands: start / stop / list / claude / opencode / run
+  server.py       # FastAPI daemon (REST + WebSocket)
+  runner.py       # PTY capture, bwrap + mitmproxy orchestration
+  proxy_addon.py  # mitmproxy addon (domain gating)
+  bwrap.py        # bubblewrap argv builder
+  profiles.py     # per-agent bind-mount profiles
+  db.py           # aiosqlite schema + queries  (~/.aleash/data.db)
+  notifications.py# notify-send wrapper
+
+frontend/src/
+  App.vue                       # root: sidebar + main panel + approval modal
+  components/SandboxList.vue    # sidebar sandbox list
+  components/SandboxDetail.vue  # tabs: Terminal | Domains
+  components/TerminalPane.vue   # xterm.js over WebSocket
+  components/DomainsPane.vue    # domain decision table
+  components/DomainApproval.vue # approval modal
+```
+
+## Adding an agent profile
+
+Edit `src/aleash/profiles.py`:
+
+```python
+_register(Profile(
+    name="myagent",
+    binary_names=["myagent"],          # binary names on PATH to auto-detect
+    extra_binds=[
+        (_home(".config/myagent"), _home(".config/myagent")),
+    ],
+    ensure_home_dirs=[".cache/myagent"],
+))
+```
+
+Then add a Click command in `cli.py` (copy the `claude` command, change the name).
+
+## Building a wheel
+
+Requires npm on PATH — the build hook runs `npm ci && npm run build` automatically for wheel builds (skipped for editable installs).
+
+```sh
+uv build
+# outputs dist/aleash-*.whl
+```
+
+## Data
+
+All state lives in `~/.aleash/`:
+
+| Path | Content |
+|------|---------|
+| `~/.aleash/data.db` | SQLite: sandboxes, terminal logs, domain decisions |
+| `~/.aleash/server.pid` | daemon PID |
+| `~/.aleash/server.log` | daemon stdout/stderr when daemonized |
+| `~/.mitmproxy/` | mitmproxy CA cert (auto-generated on first run) |
+
+Delete `~/.aleash/data.db` to reset all history.

agent_leash-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mathieu Lacage
+
+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.

agent_leash-0.3.0/Makefile

@@ -0,0 +1,11 @@
+.PHONY: all sync frontend
+
+all: sync
+
+sync:
+	uv sync
+
+# Dev server: serves UI on :5173 with hot-reload, proxies /api and /ws to the
+# mleash daemon on :7612. Run `uv run mleash start --foreground` first.
+frontend:
+	cd frontend && npm run dev

agent_leash-0.3.0/PKG-INFO

@@ -0,0 +1,18 @@
+Metadata-Version: 2.4
+Name: agent-leash
+Version: 0.3.0
+Summary: Isolated sandbox for AI coding agents
+Project-URL: Repository, https://github.com/mathieu-lacage/agent-leash.git
+Project-URL: Issues, https://github.com/mathieu-lacage/agent-leash/issues
+Author-email: Mathieu Lacage <mathieu.lacage@cutebugs.net>
+Maintainer-email: Mathieu Lacage <mathieu.lacage@cutebugs.net>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: aiosqlite>=0.20
+Requires-Dist: click>=8.1
+Requires-Dist: fastapi>=0.111
+Requires-Dist: httpx>=0.27
+Requires-Dist: mitmproxy>=10.3
+Requires-Dist: uvicorn[standard]>=0.29
+Provides-Extra: dev

agent_leash-0.3.0/README.md

@@ -0,0 +1,85 @@
+# agent-leash
+
+Sandbox runner for AI coding agents:
+
+- Restricts filesystem access to the current directory
+- Custom allow-list to expose more directories as read-only or read-write
+- Intercepts all network traffic with interactive per-domain approval
+- Controls access to host services (podman, docker, ssh-agent, etc.)
+
+```console
+$ pipx install agent-leash
+$ aleash claude
+Sandbox UI available on http://localhost:7612/
+```
+
+![aleash demo](docs/demo.gif)
+
+
+## How it works
+
+- **Filesystem** — [bubblewrap](https://github.com/containers/bubblewrap) restricts the agent to the current working directory. The rest of the filesystem is read-only or hidden.
+- **Network** — [mitmproxy](https://mitmproxy.org/) intercepts all outbound HTTPS. Each new domain triggers a browser popup (and desktop notification). You choose: always allow, allow once, always block, or block once.
+- **Web UI** — Vue 3 + xterm.js frontend served on `localhost:7612`. Shows live terminal output, domain decisions
+
+## Requirements
+
+| Tool | Install |
+|------|---------|
+| `bwrap` (bubblewrap) | `dnf install bubblewrap` / `apt install bubblewrap` |
+| `xdg-dbus-proxy` | `dnf install xdg-dbus-proxy` / `apt install xdg-dbus-proxy` |
+| Python ≥ 3.11 | system or [pyenv](https://github.com/pyenv/pyenv) |
+
+`mitmproxy` is installed automatically as a Python dependency.
+
+## Usage
+
+### Pass arguments
+
+```sh
+aleash claude -- --dangerously-skip-permissions
+aleash run python script.py --some-flag
+```
+
+### Terminal size
+
+By default the local terminal controls the PTY size. The browser shows the fixed-size terminal with scrollbars. Use `--browser-master` to invert this (browser FitAddon resizes the PTY):
+
+```sh
+aleash --browser-master claude
+```
+
+### Profile override
+
+```sh
+aleash --profile generic claude   # run claude with the generic profile
+```
+
+## Profiles
+
+| Profile | What it binds |
+|---------|--------------|
+| `claude` | `~/.claude`, `~/.claude.json`, `~/.gitconfig`, `~/.local/share/claude` |
+| `opencode` | `~/.opencode`, `~/.gitconfig`, and opencode config/cache dirs |
+| `generic` | nothing extra |
+
+`claude` and `opencode` are auto-detected by binary name. Use `--profile` to override.
+
+## Data
+
+All state lives in `CWD/.aleash/`:
+
+| Path | Content |
+|------|---------|
+| `CWD/.aleash/data.db` | SQLite: sessions, terminal logs, domain decisions |
+| `~/.mitmproxy/` | mitmproxy CA cert (auto-generated on first run) |
+
+Delete `CWD/.aleash/data.db` to reset all history.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

agent_leash-0.3.0/RELEASE.md

@@ -0,0 +1,37 @@
+# Release process
+
+## How to create a new release
+
+The release process is fully automated via GitHub Actions. The workflow is triggered by tagging a commit with a version tag (`v*`).
+
+### Manual steps
+
+1. Bump the version in `pyproject.toml`:
+```console
+$ uv version --bump minor
+```
+
+2. Commit the version bump:
+```console
+$ git add pyproject.toml
+$ git commit -m "release: $(uv version --short)"
+```
+
+3. Create a version tag (must match the version in `pyproject.toml`):
+```console
+$ git tag v$(uv version --short)
+```
+
+4. Push to GitHub (triggers the release workflow):
+```console
+$ git push github main --tags
+```
+
+### What happens next (automated)
+
+The `.github/workflows/release.yml` workflow automatically:
+
+1. **Validates** the tag matches the version in `pyproject.toml`
+5. **Builds** the Python distribution (wheel + sdist)
+6. **Publishes to PyPI** (via OIDC Trusted Publisher, no token needed)
+8. **Creates a GitHub Release** with both the Python dist and the squashfs artifact

agent_leash-0.3.0/frontend/eslint.config.js

@@ -0,0 +1,36 @@
+import js from '@eslint/js'
+import tseslint from 'typescript-eslint'
+import pluginVue from 'eslint-plugin-vue'
+import globals from 'globals'
+
+export default tseslint.config(
+  js.configs.recommended,
+  ...tseslint.configs.recommended,
+  ...pluginVue.configs['flat/recommended'],
+  {
+    files: ['**/*.vue', '**/*.ts'],
+    languageOptions: {
+      globals: {
+        ...globals.browser,
+      },
+      parserOptions: {
+        parser: tseslint.parser,
+        project: './tsconfig.json',
+        extraFileExtensions: ['.vue'],
+        sourceType: 'module',
+      },
+    },
+    rules: {
+      'vue/multi-word-component-names': 'off',
+      '@typescript-eslint/no-explicit-any': 'warn',
+      // Template formatting rules conflict with existing compact style
+      'vue/max-attributes-per-line': 'off',
+      'vue/singleline-html-element-content-newline': 'off',
+      'vue/multiline-html-element-content-newline': 'off',
+      'vue/attributes-order': 'off',
+    },
+  },
+  {
+    ignores: ['dist/**', 'node_modules/**'],
+  },
+)

agent_leash-0.3.0/frontend/index.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Sandbox</title>
+</head>
+<body>
+  <div id="app"></div>
+  <script type="module" src="/src/main.ts"></script>
+</body>
+</html>