leashbyte 0.1.1__tar.gz

leashbyte-0.1.1/.dockerignore

@@ -0,0 +1,19 @@
+.git
+.env
+.env.*
+!.env.example
+.venv
+venv
+__pycache__
+*.pyc
+.pytest_cache
+.ruff_cache
+.github
+ci
+scripts
+tests
+docs/*
+!docs/python-licenses.json
+!docs/THIRD_PARTY.md
+sdk/typescript/node_modules
+sdk/typescript/dist

leashbyte-0.1.1/.env.example

@@ -0,0 +1,46 @@
+# Copy this file to .env and give each of the eight secrets below its own random value.
+# openssl rand -hex 32 generates a suitable one.
+LEASHBYTE_API_KEY=replace-with-a-random-api-key
+LEASHBYTE_SEARXNG_SECRET_KEY=replace-with-a-different-random-secret
+LEASHBYTE_SERVICE_KEY=replace-with-a-random-service-key
+LEASHBYTE_VAULT_MANAGE_KEY=replace-with-a-random-vault-manage-key
+LEASHBYTE_VAULT_RESOLVE_KEY=replace-with-a-random-vault-resolve-key
+LEASHBYTE_CDP_KEY=replace-with-a-random-cdp-capability-key
+LEASHBYTE_VAULT_MASTER_KEY=replace-with-a-random-vault-master-key
+LEASHBYTE_POSTGRES_PASSWORD=replace-with-a-random-postgres-password
+
+LEASHBYTE_BIND_ADDRESS=127.0.0.1
+LEASHBYTE_PORT=8080
+LEASHBYTE_MCP_BIND_ADDRESS=127.0.0.1
+LEASHBYTE_MCP_PORT=8081
+LEASHBYTE_SEARXNG_BASE_URL=http://searxng:8080
+LEASHBYTE_BROWSER_POOL_BASE_URL=http://browser-pool:8082
+LEASHBYTE_VAULT_BASE_URL=http://vault:8081
+LEASHBYTE_FETCH_TIMEOUT_SECONDS=20
+LEASHBYTE_FETCH_MAX_BYTES=2000000
+LEASHBYTE_FETCH_MAX_REDIRECTS=5
+LEASHBYTE_SEARCH_MAX_RESULTS=10
+LEASHBYTE_PRIVATE_NETWORK_ALLOWLIST=
+LEASHBYTE_BROWSER_MAX_SESSIONS=2
+LEASHBYTE_BROWSER_LEASE_SECONDS=900
+LEASHBYTE_CDP_GRANT_SECONDS=60
+LEASHBYTE_BROWSER_PLUGINS_ENABLED=false
+LEASHBYTE_BROWSER_PLUGIN_MODULES=
+LEASHBYTE_LOCAL_MODEL_BASE_URL=
+LEASHBYTE_COMPOSE_SUBNET=172.29.250.0/24
+LEASHBYTE_COMPOSE_GATEWAY=172.29.250.1
+LEASHBYTE_LOCAL_MODEL_PORT=11434
+# Needed for local agent runs: the model name your server exposes.
+LEASHBYTE_LOCAL_MODEL_NAME=
+LEASHBYTE_LOCAL_MODEL_API_KEY=
+LEASHBYTE_LOCAL_MODEL_API_KEY_FILE=
+LEASHBYTE_MODEL_TIMEOUT_SECONDS=120
+LEASHBYTE_AGENT_POLL_SECONDS=0.5
+# Optional: path to an Anthropic API key file (mode 600) outside this repository.
+# Leave it empty if you only use local models.
+LEASHBYTE_ANTHROPIC_API_KEY_HOST_FILE=
+LEASHBYTE_WEB_BOT_AUTH_KEY_FILE=
+LEASHBYTE_WEB_BOT_AUTH_HOST_KEY_FILE=
+LEASHBYTE_WEB_BOT_AUTH_KEY_ID=
+# Optional, for a controlled private HTTPS test fixture only: its SHA-256 SPKI value.
+LEASHBYTE_BROWSER_TLS_SPKI_ALLOWLIST=

leashbyte-0.1.1/.github/workflows/ci.yaml

@@ -0,0 +1,110 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Install uv
+        run: python -m pip install uv==0.13.4
+      - name: Install locked dependencies
+        run: uv sync --locked
+      - name: Lint
+        run: |
+          uv run ruff check src tests sdk/python/src examples ci/mcp_roundtrip.py scripts/python_licenses.py
+          uv run ruff format --check src tests sdk/python/src examples ci/mcp_roundtrip.py scripts/python_licenses.py
+      - name: Check the Python licence inventory
+        run: uv run python scripts/python_licenses.py --check
+      - name: Test essential security and API contracts
+        run: uv run pytest -q tests
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: npm
+          cache-dependency-path: sdk/typescript/package-lock.json
+      - name: Check the TypeScript SDK and JavaScript licences
+        run: |
+          npm ci --prefix sdk/typescript
+          uv run python scripts/generate_openapi.py
+          uvx --from datamodel-code-generator==0.91.0 datamodel-codegen \
+            --input openapi.json \
+            --input-file-type openapi \
+            --output sdk/python/src/leashbyte_sdk/_models.py \
+            --output-model-type pydantic_v2.BaseModel \
+            --use-standard-collections \
+            --use-annotated \
+            --enum-field-as-literal all \
+            --target-python-version 3.13 \
+            --use-schema-description \
+            --use-field-description \
+            --disable-timestamp
+          uv run ruff format sdk/python/src/leashbyte_sdk/_models.py
+          npm --prefix sdk/typescript run generate
+          git diff --exit-code -- openapi.json sdk/python/src/leashbyte_sdk/_models.py sdk/typescript/src/schema.ts
+          npm --prefix sdk/typescript test
+          npm --prefix sdk/typescript run licenses
+          git diff --exit-code -- sdk/typescript/THIRD_PARTY_LICENSES.json
+
+  site:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: npm
+          cache-dependency-path: site/package-lock.json
+      - name: Install locked site dependencies
+        run: npm ci --prefix site
+      - name: Build the static site
+        run: npm --prefix site run build
+
+  compose-smoke:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Install uv
+        run: python -m pip install uv==0.13.4
+      - name: Install locked dependencies
+        run: uv sync --locked
+      - name: Create local configuration
+        run: |
+          cp .env.example .env
+          sed -i "s/replace-with-a-random-api-key/$(openssl rand -hex 32)/" .env
+          sed -i "s/replace-with-a-different-random-secret/$(openssl rand -hex 32)/" .env
+          sed -i "s/replace-with-a-random-service-key/$(openssl rand -hex 32)/" .env
+          sed -i "s/replace-with-a-random-vault-manage-key/$(openssl rand -hex 32)/" .env
+          sed -i "s/replace-with-a-random-vault-resolve-key/$(openssl rand -hex 32)/" .env
+          sed -i "s/replace-with-a-random-cdp-capability-key/$(openssl rand -hex 32)/" .env
+          sed -i "s/replace-with-a-random-vault-master-key/$(openssl rand -hex 32)/" .env
+          sed -i "s/replace-with-a-random-postgres-password/$(openssl rand -hex 32)/" .env
+          printf '%s\n' 'LEASHBYTE_PRIVATE_NETWORK_ALLOWLIST=host.docker.internal:18765' >> .env
+      - name: Start the controlled HTTP fixture
+        run: python ci/http_fixture.py &
+      - name: Start and check the Compose stack
+        run: |
+          docker compose up --build -d --wait
+          bash ci/compose-smoke.sh
+          LEASHBYTE_API_KEY="$(sed -n 's/^LEASHBYTE_API_KEY=//p' .env)" uv run python ci/mcp_roundtrip.py
+      - name: Show service logs after a failure
+        if: failure()
+        run: docker compose logs --no-color
+      - name: Stop the Compose stack
+        if: always()
+        run: docker compose down -v

leashbyte-0.1.1/.gitignore

@@ -0,0 +1,46 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+venv/
+dist/
+build/
+
+# JavaScript
+node_modules/
+.npm/
+*.tsbuildinfo
+
+# Local configuration and secrets
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+*.p12
+*.pfx
+secrets/
+credentials/
+
+# Runtime data
+artifacts/
+profiles/
+runs/
+*.sqlite
+*.sqlite3
+
+# Editors and operating systems
+.idea/
+.vscode/
+.DS_Store
+Thumbs.db
+
+# Logs and coverage
+*.log
+coverage/
+.coverage
+htmlcov/

leashbyte-0.1.1/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+## 0.1.1 - 2026-11-10
+
+The first release on PyPI, as `leashbyte` and `leashbyte-sdk`. 0.1.0 was a GitHub-only release and was never uploaded to a package registry. There are no code changes.
+
+### Changed
+
+- The READMEs and the project site now give the PyPI install lines.
+- `leashbyte` now requires `leashbyte-sdk>=0.1.1,<0.2`. Before, it accepted any version.
+
+## 0.1.0 - 2026-11-10
+
+First public source release.
+
+### Added
+
+- Web search through a separate SearXNG service.
+- Page fetch with Markdown, cleaned HTML and parsed JSON output, with time, size and redirect limits.
+- Destination checks on fetch and browser traffic, so neither can reach internal addresses by default.
+- Isolated Chrome sessions with named profiles, page actions and short-lived CDP access.
+- An encrypted credential vault that only fills a credential on the exact origins it's granted to.
+- Goal-driven agent runs with limits, cancellation, run records and artifacts.
+- A local run viewer.
+- An MCP server with stable search, fetch, browser and run tools.
+- Python and TypeScript SDKs.
+- A Docker Compose stack for local use, and a static project site.
+- API key authentication, a security policy and Apache-2.0 licensing.
+
+### Notes
+
+LeashByte is pre-alpha. Install it from GitHub and run it with Docker Compose. The PyPI and npm packages aren't published yet and the project site isn't deployed. [Known limits and next steps](docs/ROADMAP.md) lists what's still open.

leashbyte-0.1.1/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+info@leashbyte.com.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of public interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

leashbyte-0.1.1/CONTRIBUTING.md

@@ -0,0 +1,42 @@
+# Contributing to LeashByte
+
+LeashByte is pre-alpha and the API and security boundaries are still settling, so please open an issue before you start on anything substantial. It saves you writing a change that clashes with something already planned.
+
+## Running the checks
+
+You'll need Docker with the Compose plugin, Python 3.13 with uv 0.13.4, and Node 20 or later (22.12 or later if you build the site). From the repository root:
+
+```bash
+uv sync --locked
+uv run ruff check src tests sdk/python/src examples ci/mcp_roundtrip.py scripts/python_licenses.py
+uv run ruff format --check src tests sdk/python/src examples ci/mcp_roundtrip.py scripts/python_licenses.py
+uv run python scripts/python_licenses.py --check
+uv run pytest -q tests
+npm ci --prefix sdk/typescript
+npm --prefix sdk/typescript test
+npm --prefix sdk/typescript run licenses
+```
+
+CI runs the same checks on every push to `main` and every pull request, builds the static site and starts the Compose stack for a smoke test. If you change a route's contract, regenerate `openapi.json` and the SDK models as the [README](README.md#development) describes.
+
+## What a good pull request looks like
+
+- It does one thing. Unrelated formatting changes and refactors make a change harder to review, so send those separately.
+- The description says what changed, how you checked it and anything it doesn't cover yet. Link the issue it relates to.
+- It comes with tests where they matter most: security boundaries, parsers of untrusted input and the fix for a bug, so the bug stays fixed.
+- It fits the architecture in [docs/DESIGN.md](docs/DESIGN.md). If you think the design should change, say so in the issue first.
+- It contains no credentials, private data, internal host names or internal paths, not even in test fixtures.
+
+A maintainer reviews every pull request. Security-sensitive changes, and especially anything touching server-side fetch, browser access or the vault, get an extra security review.
+
+## New dependencies
+
+LeashByte is Apache-2.0, and we want anyone to be able to use, modify and redistribute it under those terms without picking up extra obligations. So new code and dependencies need Apache-2.0-compatible licences, such as Apache-2.0 or MIT. AGPL, SSPL and MPL projects stay outside the repository. The licence checks above fail on anything unknown, and when you add a dependency, please keep any copyright and NOTICE files it requires.
+
+## Reporting a vulnerability
+
+Please don't use a public issue or pull request for this. Email `security@leashbyte.com`. [SECURITY.md](SECURITY.md) has the details.
+
+## Licence and conduct
+
+By submitting a contribution, you agree that the project may distribute it under Apache-2.0. The [Contributor Covenant](CODE_OF_CONDUCT.md) applies in all project spaces and when you represent the project in public.

leashbyte-0.1.1/Dockerfile

@@ -0,0 +1,43 @@
+FROM ghcr.io/astral-sh/uv:0.13.4 AS uv
+
+FROM python:3.13-slim AS builder
+COPY --from=uv /uv /uvx /bin/
+WORKDIR /app
+ENV UV_COMPILE_BYTECODE=1 UV_LINK_MODE=copy
+COPY pyproject.toml uv.lock README.md LICENSE NOTICE ./
+COPY sdk/python ./sdk/python
+RUN uv sync --locked --no-dev --no-install-project --no-editable
+COPY src ./src
+RUN uv sync --locked --no-dev --no-editable
+
+FROM python:3.13-slim AS runtime
+RUN groupadd --gid 10001 leashbyte && useradd --uid 10001 --gid leashbyte --no-create-home leashbyte \
+    && mkdir -p /data/profiles /data/vault /data/run-artifacts \
+    && chown -R leashbyte:leashbyte /data
+WORKDIR /app
+ENV PATH="/app/.venv/bin:$PATH" PYTHONUNBUFFERED=1
+COPY --from=builder --chown=leashbyte:leashbyte /app/.venv /app/.venv
+COPY --from=builder --chown=leashbyte:leashbyte /app/src /app/src
+COPY LICENSE NOTICE /app/
+COPY docs/python-licenses.json docs/THIRD_PARTY.md /app/docs/
+COPY sdk/typescript/THIRD_PARTY_LICENSES.json /app/sdk/typescript/
+USER leashbyte
+EXPOSE 8080
+CMD ["uvicorn", "leashbyte.main:create_app", "--factory", "--host", "0.0.0.0", "--port", "8080"]
+
+FROM python:3.13-slim AS browser
+WORKDIR /app
+ENV PATH="/app/.venv/bin:$PATH" PYTHONUNBUFFERED=1 PLAYWRIGHT_BROWSERS_PATH=/opt/playwright
+COPY --from=builder /app/.venv /app/.venv
+RUN playwright install --with-deps chrome \
+    && groupadd --gid 10001 leashbyte \
+    && useradd --uid 10001 --gid leashbyte --create-home leashbyte \
+    && mkdir -p /data/profiles \
+    && chown -R leashbyte:leashbyte /data /opt/playwright
+COPY --from=builder --chown=leashbyte:leashbyte /app/src /app/src
+COPY LICENSE NOTICE /app/
+COPY docs/python-licenses.json docs/THIRD_PARTY.md /app/docs/
+COPY sdk/typescript/THIRD_PARTY_LICENSES.json /app/sdk/typescript/
+USER leashbyte
+EXPOSE 8082
+CMD ["uvicorn", "leashbyte.browser_service:create_browser_app", "--factory", "--host", "0.0.0.0", "--port", "8082"]