Deploy and operate
View Markdown

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:

SettingNew managed installation
HTTP listener127.0.0.1 and the approved port
DatabaseSQLite at an explicit absolute path in the selected user-data directory
DashboardEnabled
Access modedisabled
Legacy bearer authenticationDisabled, with no token
MCPUses the same local access mode as HTTP
ModelsNo 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.

ObservationStartup behavior
Database and recovery evidence are absentnew; only the approved Server startup may initialize storage.
Existing storage passes the exact target's complete checkexisting_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 helperBlock startup and preserve storage.
Interrupted maintenance/restore, rollback journal, active maintenance lock, orphan sidecars, unsafe location, or changing sourceBlock 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.

On this page