recto-core 1.0.0

Phone-enclave-rooted capability authorization substrate for autonomous agents. Cross-platform service supervision, vault-backed secrets, capability JWS verification.

Recto

Modern Windows-service wrapper. Spiritual successor to NSSM with a 2026 feature set.

Why Recto

NSSM has been the canonical "wrap an executable as a Windows service" tool since 2003 and remains rock-solid at that primitive. But the world it was built for didn't have OpenTelemetry, didn't have GitOps, didn't have hardware-enclave secret stores, and didn't have the threat model where production secrets sitting in plaintext registry keys is a real attack surface. Recto picks up where NSSM stops:

• Vault-backed secrets. Service env vars never sit in plaintext on disk. Pulled from Windows Credential Manager (DPAPI-encrypted) at process start, or from any pluggable backend.
• HTTP liveness probes with configurable thresholds and exponential-backoff restart.
• Restart-event webhooks post structured JSON to any URL when the supervised process crashes, restarts, or fails health checks.
• Declarative YAML config that lives in the consuming repo, reviewable in PRs. Replaces imperative nssm set ... PowerShell.
• Win32 Job Object resource limits for memory, CPU, process count.
• OpenTelemetry traces for every lifecycle event.
• Pluggable secret-source backends — Credential Manager (Windows), Keychain (macOS), Secret Service (Linux), AWS Secrets Manager, HashiCorp Vault — and the architectural seam for hardware-enclave backends with biometric release.

Recto wraps NSSM today; v0.2+ may absorb the service-registration responsibility natively.

Status

v1.0 released. First public OSS release; not yet on PyPI. See CHANGELOG.md for the per-feature history and ROADMAP.md for what's next.

Quick start

Recto runs on Python 3.10+. The canonical first-time setup uses a project-local virtual environment so the editable install doesn't touch your system Python:

# Windows (PowerShell):
git clone https://github.com/erikcheatham/Recto.git
cd Recto
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[v0_4]"

# macOS / Linux:
git clone https://github.com/erikcheatham/Recto.git
cd Recto
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[v0_4]"

The [v0_4] extra pulls in the cryptography + pyjwt dependencies the v0.4 protocol needs. Without it, the bootloader's verifier paths raise on import.

After install, smoke-check:

python -c "import recto; print(recto.__version__)"

For the bootloader-side launcher (the bridge between your application and a paired phone), see INTEGRATION.md and the example launcher at examples/run_bootloader_consumer.py (env-var-parameterized; ships unmodified to every consumer).

Re-cloning? A fresh git clone does NOT include any prior .venv. After every clone, repeat the python -m venv .venv + pip install -e ".[v0_4]" step. The editable install only stores a path pointer; rebuilding the venv is fast (~30s).

Distribution model

Recto distributes as three packages targeting three audiences via three channels:

• recto-core (PyPI) — the Substrate. Bootloader server + launcher (NSSM-replacement) + dpapi-machine vault + vault CLI + NSSM-migration tooling + server-side verifier libraries. Install on the host you administer.
• recto-client-{py,ts,cs} (PyPI / npm / NuGet) — the Agent SDKs. Wire-protocol clients for programs that consume capability authority. Add as a library dependency to your app.
• Recto Phone (App Store / Play Store) — the Consumer. One canonical multi-tenant MAUI app supporting pairing with N orchestrators simultaneously (Authy model, not bank-app-per-bank model). Install from the OS store.

Three audiences (DevOps + application developers + humans) get different distribution channels matching how they actually consume the substrate. See PACKAGING.md for the full architectural decision, pre-v1.0 → post-v1.0 migration plan, dependency graph, and versioning policy.

License

Apache 2.0. See LICENSE.

Architecture

See ARCHITECTURE.md for the design doc — pluggable backends, YAML schema, NSSM relationship, threat model.

Integrating with Recto

See INTEGRATION.md for the practical "how do I plug my app into Recto" guide — agent registration, capability-request wire shapes, claim schema, reference implementations in Python + C#, and production hardening checklist.

Lineage

NSSM (the Non-Sucking Service Manager) by Iain Patterson, 2003-2017, public domain. Recto stands on its shoulders for the service-registration primitive and aims to keep the give-it-away spirit alive under a license that adds explicit patent grants for the modern era.