satoru/AGENTS.md

Satoru Agent Notes

Project Intent

Satoru is a restic-based backup control plane for Linux hosts over SSH.

Core model:

1. Satoru pulls from edge hosts (no direct edge->B2 writes).
2. Stages data locally.
3. Runs restic locally for deduplicated snapshots.
4. Syncs restic data to B2 (scheduled).

Current Direction

1. Background job execution for site operations.
2. Preflight-first workflow before full backup runs.
3. Strong operational visibility through structured logs and job events.

Run The Server

cd /Users/peterli/git/satoru
go run ./cmd/satoru

Default URL:

• http://localhost:8080

Logging

Satoru uses structured logging and supports:

1. LOG_FORMAT=console|json (default json)
2. LOG_LEVEL=debug|info|warn|error (default info)
3. LOG_FILE=/path/to/file.log (optional; logs still go to stdout)

Examples:

LOG_FORMAT=console LOG_LEVEL=debug go run ./cmd/satoru

LOG_FORMAT=json LOG_LEVEL=debug LOG_FILE=./logs/satoru.log go run ./cmd/satoru
tail -f ./logs/satoru.log | jq

Debug Logging Expectation

Be proactive with debug-level logging for:

1. DB state changes (job/site/session mutations).
2. Job lifecycle transitions and step boundaries.
3. Scan and backup target-level decisions/results.
4. External command start/finish, duration, and failures.

Logs should include useful identifiers where possible:

• job_id, site_id, job_type, target_path, target_mode, status, error.