Managed local Server installation
The independent Ops tool prepares a fixed Server runtime and manages its current-user service. Ops has its own interpreter and dependencies, so repairing a missing Server interpreter does not require the damaged environment to run. Desktop integration uses this boundary; a running HTTP connection is not required for installation or repair.
Installation and repair plans
Installation and repair use the explicit preflight, apply, operation_status, cancel, and resume protocol
described in Local Server operations. The caller displays the complete plan and obtains approval
before applying it. Retain the operation ID when starting a request; after interruption, inspect the saved attempt and
current facts before approving a recovery plan.
If a later stop operation supersedes an interrupted repair, approve a new repair plan instead of resuming the superseded operation. The new plan can continue the original repair guard only after checking its journal, installation and resource identities, exact service definition, and completed native commands. It does not restart the service or restore a registration that was subsequently removed.
The packaged Ops interpreter accepts one JSON request per process. Its trusted host supplies the protected catalog and the SHA-256 digest pinned by the distribution:
<ops-python> -I -S -B <ops-entry.py> --catalog-file <protected-catalog.json> --catalog-sha256 <trusted-sha256>For example, send this single line on standard input to inspect a first installation:
{"protocol_version":1,"request_id":"inspect-install","action":"preflight","operation":"install","options":{}}The response includes the fixed resource, program/configuration/data locations, endpoint, database classification,
required space, and startup effects. Pass the returned complete plan unchanged to apply, with a unique operation ID
and explicit authorization for its plan_id, as in the shared Ops protocol. To prepare same-version repair, use
"operation":"repair". Managed locations are selected by the host; --state-dir belongs to the separate operator-owned
--target-file mode and cannot override a managed installation. These commands require a qualified producer catalog;
they do not discover a public release or produce one.
Only the trusted producer selects resource URLs, executable layout, platform, architecture, package version, and file digests. The renderer cannot supply a command, download URL, or arbitrary installation path. Resources are downloaded to staging, checked against the fixed catalog, and verified before publication. A checksum supplied alongside an untrusted download does not establish trust. A cache hit must pass the same integrity checks as a download.
Repair uses the same fixed resource identity and version. It preserves the installation identity, existing
configuration, and user data. It does not upgrade to latest, reset authentication or models, or delete an existing
database. Repair stops the owned service before replacing resources and completes without restarting it. A stopped
service stays stopped. Repeating installation for a verified current installation reports current
facts without restarting the service or opening its database.
Managed service definitions explicitly select isolated runtime startup (isolated_runtime=true). The target Python
runs with -I -B, excluding PYTHONPATH and user-site imports and avoiding generated bytecode changes in the verified
resource tree. Manage these definitions with the bundled Ops tool or a matching-version service tool. Older CLI
versions that do not recognize this field reject the definition; they are not a supported way to manage the new
registration. Existing definitions without this field retain their previous startup behavior.
An independent installation is not automatically adopted. Unknown ownership, damaged control records, mismatched native service definitions, or unresolved native commands require inspection before modification. Removing a service registration preserves the environment, configuration, and database; it is not a database deletion operation.
New personal configuration
The new-configuration policy explicitly sets:
| Setting | New managed installation |
|---|---|
| HTTP listener | 127.0.0.1 and the approved port |
| Database | SQLite at an explicit absolute path in the selected user-data directory |
| Dashboard | Enabled |
| Access mode | disabled |
| Legacy bearer authentication | Disabled, with no token |
| MCP | Uses the same local access mode as HTTP |
| Models | No generation, embedding, reranking, or decision model is configured |
This is local access without a token, not a separate anonymous credential. Keep the listener on loopback. The policy does not change authentication for existing or remote connections, and repair does not overwrite an existing user's choices. Selecting an authenticated existing installation retains its protected configuration.
The default data directory follows the platform's powercontext_data_dir() location while ignoring an inherited
POWERCONTEXT_HOME. New configuration also ignores inherited POWERCONTEXT_SERVER_*, PYTHONPATH, and PYTHONHOME
settings during resolution. It records the chosen data root and SQLite path explicitly. Existing installations retain
their verified registered data directory; program directories and data directories are separate.
Preflight reads configuration through the protected-file interface and returns only the file identity and necessary local summary fields. Configuration contents, tokens, and model credentials do not enter plans or operation journals. Preflight does not create a configuration file, data directory, or database.
Database compatibility boundary
Passive inspection inventories the selected SQLite file and recovery sidecars without opening SQLite or starting a
target process. Existing files remain existing_unknown in ordinary status. Program-only repair binds the file
identity and target version, allows normal writes and WAL checkpointing during resource preparation, and completes
with the service stopped. Replacing the database invalidates its repair plan.
Operations that can start the managed service perform a separate admission check: start, restart, registration,
and configuration changes that actually restart an active service. Ops verifies the owned target resource against its
fixed manifest, then invokes that bundle's Server admission entry with isolated Python (-I -B). Windows uses the
manifest's console Python from the same bundle. The child checks its installed package version against the selected
Server version. An older target without this entry remains unsupported; the Ops package version or a previous
successful startup cannot replace target admission.
The target checks the complete Server schema and indexes, supported revision history, configured domains and embedding profile, SQLite integrity, original-path maintenance evidence, and unfinished archive restores. It reads a private copy of the main database and WAL, including committed data not yet checkpointed into main. The original database is never opened by SQLite during admission; its SHM is neither copied nor changed, and no original sidecars are created or removed. File identities and modification evidence must remain stable while copying and checking. Admission performs no initialization, migration, restoration, model call, HTTP startup, or worker startup.
| Observation | Startup behavior |
|---|---|
| Database and recovery evidence are absent | new; only the approved Server startup may initialize storage. |
| Existing storage passes the exact target's complete check | existing_ready for that explicit admission; same-version startup and restart require unchanged storage through apply. |
| Unknown schema, empty existing file, older layout, future revision, unsupported profile, or missing target helper | Block startup and preserve storage. |
| Interrupted maintenance/restore, rollback journal, active maintenance lock, orphan sidecars, unsafe location, or changing source | Block startup and preserve recovery evidence. |
A revision marker or a partial domain check is insufficient. Required migrations and recovery remain explicit
operator work under Database migrations. database_migration_required,
database_recovery_required, and database_configuration_mismatch identify those boundaries;
database_compatibility_unknown means the exact target could not establish compatibility. Repair changes programs
only and does not remove these requirements.
Admission copies and hashes the complete main file and WAL, then scans the snapshot using Server validators. Each
preflight and apply revalidation repeats this work; it is not an incremental or cached check. The combined main/WAL
limit is 8 GiB, the temporary filesystem needs their combined size plus 32 MiB free, and copying plus target
validation has a 120-second deadline. Oversize, insufficient space, and timeout return
database_snapshot_too_large, database_snapshot_space_insufficient, and database_admission_timeout. Recovery
journals are limited to 4 MiB each. Large or busy databases require an operator-controlled maintenance workflow;
raising a limit does not establish compatibility. Temporary copies are removed after the check.
Normal writes also invalidate approved database evidence. If the running Server keeps writing, or data changes
between preflight and apply, stop it through Ops, obtain a fresh start plan after writes have stopped, and approve
that plan. A rejected restart leaves the running service unchanged. Admission does not automatically stop writers or
relax the approved database identity; other processes writing the same database must also be quiescent.
A local macOS arm64 / CPython 3.12.15 measurement with 2,000 public Memory records, 4,000 revisions and a 168.4 MiB SQLite main file took 3.78–3.86 seconds per admission across three runs; copying and hashing took 0.074–0.075 seconds. Source hashes remained unchanged. This measurement excludes resource-manifest verification and native service commands and does not qualify other machines, WAL sizes, or databases near the limit.
Apply repeats admission and compares the approved plan's database, configuration, target-resource and recovery
evidence. Changed evidence rejects the old plan before a service command. The running Server still owns its normal
startup checks. Inspection, stopping, registration removal, and stopped program repair remain available when the
target interpreter is damaged or absent. A stopped service stays stopped
when configuration changes request restart=true. The independent prepared-runtime operator binding retains its
existing contract.
Startup and connection handoff
Resource integrity, configuration validity, service registration, process liveness, and readiness are separate facts. For an approved first startup, the shared service controller performs bounded readiness verification and protects and stops a newly started owned target when startup fails. A completed installation result is historical evidence; ordinary status does not rerun readiness checks. Cancellation takes effect at supported safe boundaries and does not promise rollback.
If first registration fails before creating a service, release the conflicting port or resolve the reported failure, then confirm a fresh install plan and resume the recorded operation. The installation identity and owned configuration are retained. A dispatch checkpoint alone does not establish that registration existed. Matching-version CLI and Ops removal persist a private removal identity before native changes; an older install operation cannot undo that removal, even when no registration existed yet. Pending records without this identity remain readable, but a legacy dispatch checkpoint without registration evidence requires inspection rather than automatic replay.
A cancelled installation can reuse verified staging. If regular staged files are corrupt, resume or a new approved install operation verifies the recorded directory ownership, discards that exact staging tree and prepares the fixed resource again. Replaced directories, links and unsafe ownership are rejected and preserved.
The installer returns its actual endpoint and installation/resource identities. These are not Server deployment or Principal identities. The connection layer must validate the actual endpoint and supported public identity and compatibility contract before activating a connection or obtaining its default Scope. Installation does not invent a Scope ID, select an arbitrary Scope, or prove that a Memory operation has succeeded.
Release and platform acceptance
This implementation requires producer-supplied, fixed resources. The candidate producer builds pinned native Server/Ops resources for Windows x86_64 and macOS arm64/x86_64 with real consumer readback. Its catalogs remain unqualified. The formal platform resource catalog and qualified artifacts belong to #2112; the implementation does not supply a public production download URL or infer one from a version string. Development fixtures and locally built bundles verify implementation behavior, not production distribution trust.
On Windows, preflight checks the producer's file layout against the actual final directory and the fixed staging
budget. Acquisition checks its exact staging directory again before downloading. Ordinary paths must fit the Windows
file and directory limits; unsupported layouts return resource_path_unsupported. Ops does not enable system-wide
long paths or assume Task Scheduler supports extended-path executable names. The producer must qualify a layout that
fits the intended user directories. A complete development bundle that starts from a shorter test directory does not
establish that the default installation layout works.
Release acceptance must use the exact downloaded artifacts on clean standard-user Windows 11 x64, macOS arm64, and macOS x86_64 machines without preinstalled Python, uv, Git, or build tools. Independently verify signatures and macOS notarization, independent Ops startup, actual Task Scheduler or LaunchAgent behavior, login/restart handling, and preservation of configuration and data through repair and removal. Fake service adapters and repository-runtime SQLite tests do not establish those platform results.

