TimeLocker provides a CLI-first interface for managing backups with Restic and related orchestration services. It covers repository management, file selection, scheduling, monitoring, and recovery workflows across local, S3-compatible, and B2 backends.
This repository is feature-rich but still being consolidated. Treat this README
and docs/README.md as the current orientation layer. Active
delivery work is indexed under docs/specs/.
The TimeLocker project charter is the enduring authority for the project mandate, operating principles, scope boundaries, governance, and measures of success. Read it when deciding whether proposed work belongs in TimeLocker; use active specs for approved delivery details.
Note: TimeLocker is a CLI-based application. It does not provide a full desktop GUI or REST API. A protected Linux deployment adds an independent optional tray for status and allowlisted backup/retention requests.
- Project description
- Project Direction
- Who this project is for
- Features
- Repository Structure
- Instructions for using TimeLocker
- More Detailed Examples
- Troubleshooting
- Data Flow
- Infrastructure
- Documentation
- Contributing
- Support
- Acknowledgements
- Terms of use
- Document Information
The library abstracts away the complexity of managing Restic commands and configurations while providing type-safe interfaces and comprehensive error handling. It supports multiple storage backends (Local, S3, Backblaze B2) with automatic credential management and validation.
This project is intended for:
- System administrators who need to set up backup solutions
- Developers who want to integrate backup functionality into their applications
- End users who want a more user-friendly interface for Restic backups
- Unified interface for managing backup repositories across different storage backends
- Smart file selection system with pattern-based inclusion/exclusion
- Built-in support for common backup patterns and file groups
- Automatic credential management for cloud storage backends
- Comprehensive error handling and logging
- Type-safe interfaces with full typing support
- Extensible architecture for adding new repository types
.
├── src/TimeLocker/ # Python package and Typer CLI
│ ├── cli.py # `timelocker` / `tl` entrypoint
│ ├── cli_modules/ # Commands, helpers, and CLI services
│ ├── services/ # Application orchestration
│ ├── config/ # Filesystem-backed configuration
│ ├── monitoring/ # Telemetry, progress, notifications
│ ├── scheduling/ # Scheduling integrations
│ ├── system_control/ # Protected backend, launcher, tray, runs
│ ├── security/ # Credentials and privacy controls
│ ├── policy/ # Policy models and persistence
│ └── restic/ # Restic repositories and commands
├── tests/TimeLocker/ # Pytest unit and integration suites
├── docs/
│ ├── 1-requirements/ # Durable product requirements
│ ├── 2-architecture/ # Current system architecture
│ ├── 3-implementation/ # Current implementation guidance
│ ├── 4-testing/ # Test strategy and environments
│ ├── guides/ # User, developer, and agent guidance
│ ├── reference/ # Current command and API references
│ ├── resources/ # Documentation images and source data
│ ├── specs/ # Temporary active delivery packages
│ └── history/ # Compact spec closure indexes
├── examples/ # Integration examples
├── resources/ # Product branding assets
├── scripts/ # Repository maintenance utilities
└── pyproject.toml # Package, dependencies, pytest, coverage
- Python 3.12 or 3.13
- Restic backup tool installed and accessible in PATH
- For cloud storage:
- S3: boto3 package (
pip install boto3) - B2: b2sdk package (
pip install b2sdk)
- S3: boto3 package (
TimeLocker is not currently published to PyPI. Install it from a source checkout:
# Clone the repository
git clone https://github.com/Auriora/TimeLocker.git
cd TimeLocker
# Create and activate a virtual environment, then install
python -m venv .venv
source .venv/bin/activate # Windows PowerShell: .venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install .
# Contributors: install the editable package and test tools instead
python -m pip install -e '.[dev]'For detailed installation instructions, including platform-specific guidance, configuration, and troubleshooting, please refer to our Installation Guide.
Administrators deploying host-level backup and retention should also read the
System Operations Requirements,
Scheduling Guide, and
Independent Tray Setup. The protected deployment
uses stable /usr/local/bin/timelocker and /usr/local/bin/tl launchers and
does not depend on pyenv or a source checkout.
# Add and initialize a local repository (file:// is required for local paths)
tl repos add myrepo file:///path/to/repo --set-default
tl repos init myrepo
# Create a backup (sources can be specified directly or via a target)
tl backup create /home/user/documents --repository myrepo
# List snapshots (for a specific repo; omit --repository to use default behavior if applicable)
tl snapshots list --repository myrepo
# Restore from a snapshot
tl snapshots restore abc123 /restore/path --repository myrepoNote: Repository credentials can be stored in TimeLocker's encrypted credential
store. Unattended access to that store requires an explicit
TIMELOCKER_MASTER_PASSWORD or protected TIMELOCKER_MASTER_PASSWORD_FILE;
backend-specific environment variables remain available as fallbacks.
TimeLocker’s modern backup flow revolves around reusable selection templates. Define the template once and reuse it through the same service layer that powers the CLI.
This repository is feature-rich but still actively being consolidated. Prefer
current guidance under docs/guides/ and docs/reference/, and consult the
active-spec index for approved work in progress.
from pathlib import Path
from TimeLocker.selection_models import (
SelectionTemplate,
SelectionConfig,
PatternRule,
PatternSyntax,
PathComponent,
)
from TimeLocker.selection_template_manager import SelectionTemplateManager
template_manager = SelectionTemplateManager()
template_manager.create_template(
SelectionTemplate(
id="home-documents",
name="Home Documents",
description="Sync ~/Documents and skip scratch files",
selection_config=SelectionConfig(
include_paths=[Path("/home/user/Documents")],
exclude_patterns=[
PatternRule(
pattern="*.tmp",
syntax=PatternSyntax.GLOB,
applies_to=PathComponent.FULL_PATH,
)
],
),
)
)Run the template through the CLI service manager (the same path used by tl backup create --selection …):
from TimeLocker.cli_services import CLIServiceManager
service_manager = CLIServiceManager()
result = service_manager.run_selection_backup(
selection_name="Home Documents",
repository="myrepo",
tags=["documents", "desktop"],
dry_run=True,
cli_options={"tool_type": "restic"},
)
print(f"Backup status: {result.status.value}")
if result.warnings:
print("Selection warnings:", result.warnings)CLI equivalent for quick smoke tests:
tl selections create home-documents --include /home/user/Documents --exclude '*.tmp'
tl backup create --selection home-documents --repository myrepo --dry-run# Configure a B2 repository and set it as default
tl repos add my-b2 --uri "b2:bucket-name/backup?account_id=abc&account_key=xyz"
tl repos set-default my-b2
# Create/preview a selection template with pattern groups
tl selections create work-docs --include /home/user/work --pattern-group office_documents
tl selections preview work-docs --limit 20
# Trigger a dry-run backup so you can review selection warnings
tl backup create --selection work-docs --dry-run --tags team=ops --verboseCommon issues and solutions:
- Repository Authentication Failures
try:
repo = manager.from_uri("s3:bucket/backup")
except RepositoryError as e:
# Check environment variables
print("AWS credentials not found:", e)- File Selection Validation
try:
selection = FileSelection()
selection.validate()
except ValueError:
print("At least one folder must be included in backup selection")- Debug Logging
import logging
logging.getLogger('restic').setLevel(logging.DEBUG)The backup process follows this general flow:
- Selection template definition and validation
- Repository initialization and credential resolution
- CLI/Service manager builds the job config and invokes the Backup Orchestrator
- Snapshot creation and management with selection metadata
[SelectionTemplateManager] --> [SelectionManager]
| |
v v
Selection Templates CLIServiceManager / BackupCLIHandler
|
v
[BackupOrchestrator] --> [Snapshot]
Key component interactions:
- SelectionTemplateManager & SelectionManager own selection definitions, previews, and validation
- CLIServiceManager/BackupCLIHandler resolve template IDs and create canonical backup job configs
- BackupRepository handles storage backend operations
- FileSelection + DataSelectionIntegration translate rules per tool
- Snapshot represents a point-in-time backup state
- Repository implementations handle backend-specific operations
- Type:
S3ResticRepository - Purpose: Manages backups in Amazon S3 buckets
- Environment: Requires AWS credentials (access key, secret key, region)
- Type:
B2ResticRepository - Purpose: Manages backups in Backblaze B2 storage
- Environment: Requires B2 credentials (account ID, application key)
- Type:
LocalResticRepository - Purpose: Manages backups in local filesystem
- Environment: Requires write access to target directory
For detailed documentation, please refer to:
- Architecture Documentation - System architecture and design
- Implementation Guides - Implementation details and patterns
- API References - API references for backup and recovery operations
- Testing Documentation - Testing guides and strategies
- System Tray Setup - Independent status and allowlisted-action tray
- User Guides - End-user documentation
- Developer Guides - Developer documentation
- System Architecture - Overall system design
- CLI Modules - CLI structure and commands
- Scheduling System - Automated backup scheduling
- Security System - Security and credential management
- Integration Layer - Service communication framework
- Documentation Status - Current documentation health
- Active Specifications - Approved work in progress
- Specification Closure Log - Compact lifecycle history
- Changelog - Release-facing notable changes
Contributions are welcome! Please read our Contributing Guide for details on our code of conduct and the process for submitting pull requests.
By participating in this project, you agree to abide by the Code of Conduct.
If you're experiencing issues with TimeLocker or have questions about its usage, please check our Support Guide for information on how to get help.
For security-related issues, please refer to our Security Policy and follow the instructions there instead of filing a public issue.
- Restic - The underlying backup tool that TimeLocker builds upon
- All contributors who have helped shape TimeLocker
This project is licensed under the GNU General Public License v3.0 (GPL-3.0). See the repository-root LICENSE file for
details.
The GPL-3.0 is a strong copyleft license that requires anyone who distributes your code or a derivative work to make the source available under the same terms. This is particularly suitable for libraries and applications that you want to remain open source.
- Version: 0.9.1
- Last Updated: 2026-08-13
- Author: Bruce Cherrington
- Copyright © Bruce Cherrington