This repository serves as a template for developing Python applications using the uv package manager. It comes pre-configured with Docker, Docker Sandboxes kits for AI agents, GitHub Actions CI, and common development tools.
This template targets non-distributed Python applications (services, internal tools, scripts) — it is not intended for building distributable libraries or wheels. It provides only the outer scaffolding (CI, containers, security tooling); the inner application code is intentionally minimal.
myapp/ is a placeholder package — rename it and replace its contents with your own. Tests are co-located under each package's tests/ directory.
- Modern Python Stack: Uses Python 3.14+ and
uvfor fast dependency management. - Containerized Development:
- Docker & Docker Compose: Provides consistent development and production environments using multi-stage builds (
dev,prod).
- Docker & Docker Compose: Provides consistent development and production environments using multi-stage builds (
- AI Agent Sandbox: Docker Sandboxes (
sbx) kits in.sandbox/run agents under stronger isolation — a microVM kernel boundary, deny-by-default networking, and credentials that never enter the VM. Launched from the host. - Development Tools: Integrated with standard development tools:
- CI/CD: GitHub Actions workflows (
.github/workflows/) — a consolidatedci.ymlruns linting, type checking, and tests (with a coverage PR comment) in a single job; companion workflows cover security scanning, SBOM generation, Dockerfile/workflow linting, and labeling. - Pre-commit Hooks:
.pre-commit-config.yamlruns ruff, pyright, and a lockfile check at commit time via prek (optional). - Shared Knowledge Base:
docs/knowledge/is an OKF bundle — a plain-Markdown knowledge base (ADRs, architecture notes, conventions, runbooks, research) that both humans and AI agents read and write. Ships as a labeled-sample skeleton; start atdocs/knowledge/index.md.
This project implements supply chain attack protections. cf. https://zenn.dev/dajiaji/articles/47164ff27d2123
- Lockfile Integrity: CI uses
uv sync --locked, which fails whenuv.lockis missing, tampered with, or out of sync withpyproject.toml - Minimum Privileges: Workflows use
permissions: {}at top level - Actions Lockfile: Every action used by the workflows — including transitive dependencies — is pinned to a verified commit in
.github/workflows/actions.lock, souses:lines reference readable release tags. The runner refuses unlocked actions,verify_lockfile.ymlchecks the lockfile on every workflow change, and Dependabot regenerates the matching entry in its version-update PRs. Docker actions are pinned by@sha256:digest, since the lockfile does not cover container images - Dependabot Cooldown: 7-day delay before accepting new package versions
- Resolution Cooldown: uv's
exclude-neweris set to7 days, souv locknever resolves to packages released within the last 7 days (kept in sync with the Dependabot cooldown) - Vulnerability Scanning: Trivy scans dependencies on dependency/Dockerfile/workflow changes and weekly — PRs fail on CRITICAL/HIGH findings;
push/scheduleruns upload SARIF results to the GitHub Security tab - SBOM Generation: CycloneDX SBOM generated on dependency changes
- Workflow Auditing: zizmor checks for workflow security issues
Note
Using this template in a private repository? The SARIF upload to the Security tab requires Code scanning, which is free for public repositories but needs GitHub Code Security for private ones — without it, the upload step fails with Resource not accessible by integration. If you keep your repository private, edit .github/workflows/security.yml to always use the table + exit-code approach instead:
- Delete the SARIF-format "Run Trivy vulnerability scanner" step and the "Upload Trivy scan results to GitHub Security tab" step.
- Remove the
if: github.event_name == 'pull_request'condition from the remaining table-format step. - Remove
security-events: writefrom the job'spermissions.
Alternatively, enable GitHub Code Security on the repository to keep the Security tab integration.
.
├── .claude/ # Claude Code settings (permissions.defaultMode: auto)
├── .dockerignore
├── .editorconfig
├── .github/ # GitHub-specific files
│ ├── copilot-instructions.md # Pointer to AGENTS.md for GitHub Copilot
│ ├── dependabot.yml # Dependabot configuration
│ ├── ISSUE_TEMPLATE/ # Issue forms (bug, feature, task)
│ ├── labeler.yml # Path-based PR labeling config (used by label_pr.yml)
│ ├── labels.yml # Repository label definitions (synced via the manual Sync Labels workflow)
│ ├── PULL_REQUEST_TEMPLATE.md
│ ├── scripts/
│ │ └── sync-labels.sh
│ └── workflows/ # GitHub Actions CI workflows
│ ├── actions.lock # Actions lockfile (generated by `gh actions-lock`; never edit by hand)
│ ├── ci.yml # Lint + type check + tests (single job)
│ ├── label_pr.yml # PR auto-labeling (actions/labeler)
│ ├── labels.yml # Label sync (manual: workflow_dispatch)
│ ├── lint_docker.yml
│ ├── lint_gha.yml
│ ├── sbom.yml # SBOM generation
│ ├── security.yml # Vulnerability scanning
│ └── verify_lockfile.yml # Checks actions.lock against the workflows (gh actions-lock --verify)
├── .gitignore
├── .pre-commit-config.yaml # Pre-commit hooks (run via prek)
├── .python-version # Specifies Python version (primarily for uv/tooling)
├── .sandbox/ # Docker Sandboxes (sbx) kits — stronger agent isolation (host-side)
│ ├── claude-auto/ # Fork kit: claude's YOLO default -> --permission-mode auto
│ ├── codex-approve/ # Fork kit: codex's YOLO default -> --approve-for-me
│ ├── kit/ # Shared mixin kit (uv, Python, prek, Codex CLI, network/credential rules)
│ └── README.md # sbx setup and host hand-off steps
├── .vscode/ # VSCode-specific files
│ └── settings.json
├── AGENTS.md # Project guidelines for AI agents and humans
├── CLAUDE.md # Pointer to AGENTS.md for Claude Code
├── Dockerfile # Defines container images (dev, prod)
├── LICENSE
├── README.md # This file
├── compose.dev.yml # Docker Compose configuration for development
├── compose.yml # Docker Compose configuration for production
├── docs/
│ └── knowledge/ # Shared knowledge base (OKF bundle): ADRs, conventions, runbooks, ...
├── myapp/ # Placeholder application package — rename and replace
│ ├── __init__.py
│ ├── main.py # Sample application code
│ └── tests/ # Co-located tests (no __init__.py — uses pytest importlib mode)
│ └── main_test.py
├── pyproject.toml # Project metadata and tool config (uv, ruff, pyright, pytest, taskipy)
└── uv.lock # Pinned versions of dependencies
After creating a repository from this template:
- Rename the
myapp/package directory to your project's name, then update every reference to it:pyproject.toml:[project] nameanddescription,--cov=myappin thetest_covtask,testpathsunder[tool.pytest.ini_options], andsourceunder[tool.coverage.run]myapp/tests/main_test.py: thefrom myapp.main import helloimport
- Fill in the
LICENSEplaceholders ([yyyy],[name of copyright owner]) — or replace the license entirely. - Replace the sample documents in
docs/knowledge/with real project knowledge (each sample carries a "replace me" banner). - If your repository is private, adjust
.github/workflows/security.ymlas described in Security (the Security-tab upload requires GitHub Code Security on private repositories). - Run the Sync Labels workflow once (Actions → Sync Labels → Run workflow) to create the project labels (e.g.
meta, used by PR auto-labeling) — label sync is manual-only. - Run
uv sync && uv run task lint && uv run task testto confirm the renamed project is healthy.
- Docker and Docker Compose
- Docker Sandboxes (
sbx) — only for running AI agents (see below) - uv (if not using Docker)
- Build the development image:
docker compose -f compose.dev.yml build
- Run commands inside the container:
For example, to run tests:
docker compose -f compose.dev.yml run --rm app <command>
To get an interactive shell:docker compose -f compose.dev.yml run --rm app task testdocker compose -f compose.dev.yml run --rm app bash
- Install
uv(if not already installed):# cf. https://github.com/astral-sh/uv?tab=readme-ov-file#installation curl -LsSf https://astral.sh/uv/install.sh | sh
- Install dependencies:
uv sync
- Run commands:
For example, to run tests:
uv run <command>
uv run task test
Install prek (preinstalled in the sbx kit) and run:
prek installThe hooks (defined in .pre-commit-config.yaml) run ruff check, ruff format --check, pyright, and uv lock --check on each commit.
Run these tasks via uv run task <name> locally, or inside the development container (docker compose run):
task lint: Run linters (ruff checkandpyright).task fix: Automatically fix linting issues withruff.task format: Format code withruff format.task test: Run tests withpytest.task test_cov: Run tests and generate coverage reports.
Example:
uv run task lint
uv run task test_covAI coding agents (Claude Code, Codex) run in an isolated environment —
a microVM kernel boundary, deny-by-default networking, and secrets that never enter the VM —
.sandbox/ ships kits for Docker Sandboxes (sbx).
Launch it from the host, e.g.:
sbx env run ./.sandbox/claude-auto # Claude Code in auto permission mode
sbx env run ./.sandbox/codex-approve # Codex in approve-for-me modesbx runs on the host OS. See .sandbox/README.md for setup and for getting the work
back to the host; docs/knowledge/runbooks/agent-sandbox-sbx.md
covers the mechanics (environment files and kit spec v3, why clone mode is mandatory, network policy, secrets, troubleshooting).