Skip to content

Contributing

Thank you for your interest in contributing to ShoreGuard! This guide covers the workflow, setup, and standards we follow.

Issue-first workflow

Before submitting a pull request, open an issue to discuss the change you have in mind. This helps avoid duplicated effort and ensures alignment on scope and approach. Once the issue is triaged, you can reference it in your PR.

Setup

git clone https://github.com/FloHofstetter/shoreguard.git
cd shoreguard
uv sync --group dev
uv run pre-commit install --hook-type pre-commit --hook-type pre-push

This installs all runtime and development dependencies in an isolated virtual environment managed by uv, and registers the pre-commit hooks described in Pre-commit hooks below.

Pre-commit hooks

ShoreGuard uses pre-commit to run all static analysis tools automatically on every git commit and git push.

On git commit (fast, seconds):

  • File hygiene: trailing whitespace, EOF newlines, YAML/JSON/TOML syntax, merge-conflict markers, large files, private keys
  • ruff check --fix (auto-fixes trivial issues and fails if any)
  • ruff format
  • pyright (type checker, whole project)
  • pydoclint (Google-style docstring enforcement)
  • yamllint (linter, beyond syntax)
  • markdownlint-cli2
  • actionlint (GitHub Actions workflow validation)
  • detect-secrets (scans for leaked credentials against .secrets.baseline)

On git push (slow, 10-30s):

  • pip-audit (dependency CVE scan — needs network)
  • mkdocs build --strict (docs build, catches broken links and mkdocstrings resolver errors)

Run all hooks manually against the full repo:

uv run pre-commit run --all-files

If a hook auto-fixes something (e.g. ruff check --fix), the commit fails once so you can stage the fixes and re-commit.

If you ever need to bypass the hooks in an emergency, use git commit --no-verify — but please re-run them before pushing.

Running the server

uv run shoreguard --local --no-auth

The server starts on http://localhost:8888 by default. The --local flag enables Docker-based gateway management, --no-auth skips login.

Clone to first sandbox

This walkthrough takes you from a fresh clone to creating your first sandbox.

Prerequisites

  • Python 3.14+, uv
  • Docker Engine running (docker info should succeed)
  • openshell CLI on PATH

Steps

1. Clone and install:

git clone https://github.com/FloHofstetter/shoreguard.git
cd shoreguard
uv sync --group dev

2. Start ShoreGuard in local mode:

uv run shoreguard --local --no-auth

This starts the server on http://localhost:8888 with SQLite, no login required, and Docker gateway management enabled.

3. Create a gateway:

Open http://localhost:8888. Click Gateways > Create Gateway. Pick a name (e.g. dev) and click Create. ShoreGuard calls openshell gateway start under the hood.

4. Create a sandbox:

Navigate to the gateway page, click Create Sandbox. The wizard walks you through selecting an image and configuring policies.

5. Verify:

You should see the sandbox listed on the gateway detail page with status "running".

Task runner

ShoreGuard uses just for common dev tasks:

just dev       # start dev server (--local --no-auth)
just check     # run full check suite
just test      # run unit tests
just format    # auto-format code
just docs      # serve docs locally
just sync      # sync dependencies

Run just --list to see all available tasks.

Check suite

Run the full check suite before pushing to make sure CI will pass:

just check

Or manually:

uv run ruff check . && uv run ruff format --check . && uv run pyright && uv run pytest -m 'not integration'

This covers linting, formatting, type checking, and unit tests in a single command.

CI requirements

All of the following checks must pass on every pull request:

  • Lint -- ruff check
  • Format -- ruff format
  • Typecheck -- pyright
  • Tests -- pytest on Python 3.14

Code style

Area Standard
Docstrings Google-style
Linting ruff
Formatting ruff format
Type checking pyright
Line length 100 characters