@ours.network/install 1.2.1-nightly.3 → 1.2.1-nightly.31

package/GATEWAY_SETUP.md

@@ -0,0 +1,178 @@
+# Set up Ours with one client connection
+
+Fleet, the `ours` CLI and MCP clients share `~/.ours-client/profile.json`.
+Set the server address once. The address is the HTTP gateway: clients append
+`/daemon`, `/cowork`, `/messenger` or `/tg-connector` as needed. They do not
+connect to server Unix sockets, discover server state directories, or try port
+3050 after a connection failure. Fleet's local supervisor/harness sockets still
+control local processes; they do not carry server management requests.
+
+## Release availability
+
+The nightly manifest selects one published dependency graph: SDK
+`3.8.1-nightly.14`, CLI `2.8.1-nightly.12`, daemon `3.8.1-nightly.6`,
+Fleet `1.2.0-nightly.17`, MCP/Codex/Claude Code `1.2.0-nightly.9`,
+Telegram `1.0.1-nightly.8`, Messenger `1.0.31-nightly.8`, and Cowork
+`1.3.3-nightly.20260926.ceab465`. Exact archive checksums are retained in
+`releases/nightly.json`; the host CLI uses the same SDK/CLI pair.
+
+The coordinated installer release must include these pins before using the
+commands below. Its release gate verifies the actual registry and vendored
+package graphs, client acquisition/retry, and rejection of dependency drift.
+These checks do not deploy or certify an existing server installation.
+
+The daemon includes ADAPT SDK/native `0.12.1` and the shutdown socket-reset
+correction from [SDK PR70](https://github.com/adapt-toolkit/ours-sdk/pull/70).
+Client profile commands do not control server processes.
+
+## Fresh full-stack setup on localhost:4050
+
+For an agent asked to “put the daemon on localhost port 4050”, use **4050 as the
+public gateway port**. The daemon's internal container port stays 3050. Docker
+publishes only the gateway. Run as the user who will run Fleet and the harnesses.
+Use Node.js 22+ and a working Docker Compose installation.
+
+```sh
+npm install -g @ours.network/install@nightly
+ours-install all install --mode docker \
+  --state-dir "$HOME/ours-server" --identity-name "Your Name" \
+  --port 4050 --integrations codex,claude-code
+```
+
+The installer starts the server, retains or creates its Human identity, issues a
+separate client credential, and imports the connection into `~/.ours-client`.
+For Fleet, add `fleet` to `--integrations` and provide
+`--fleet-settings /absolute/path/fleet-settings.json`; see the Fleet settings
+example in [assets/fleet-settings.example.json](assets/fleet-settings.example.json).
+The example selects Codex for all three jobs; review its model and subscription
+against the installed Fleet catalog before use. The installer prepares Fleet but leaves it
+stopped for review. Use `--dry-run` first to inspect a complete preset.
+
+Do not set `OURS_PORT=4050` in a client shell, Fleet role, or user service. The
+single profile contains `serverUrl: "http://127.0.0.1:4050"`, with daemon requests
+at `http://127.0.0.1:4050/daemon` and Cowork management at
+`http://127.0.0.1:4050/cowork/management/rpc`.
+
+## Existing or remote server
+
+An older Docker installation needs its gateway enabled on the **server host**:
+
+```sh
+ours-install server gateway-enable --state-dir "$HOME/ours-server"
+```
+
+This is a server migration that may restart its services; perform it in an
+approved maintenance window. Do not change identities or reinstall a populated
+server to change a client address. `--port` on an existing installation cannot
+silently move the retained public port.
+
+For a remote host, expose the gateway through an authenticated HTTPS entrypoint
+and select that URL when installing the server, for example
+`--server-url https://ours.example.net/base`. The reverse proxy must preserve the
+base prefix, streaming responses and WebSocket upgrades. Do not expose the
+individual service ports.
+
+Obtain an issued credential using `ours-install server access-issue --state-dir
+/absolute/server/root --output /private/credential` on the server. Transfer it
+privately to the client user. Never print the credential or put it into command
+arguments, source control, chat, or a service unit. Use a private directory
+(mode 0700) and credential/profile files (mode 0600).
+
+Prepare a client profile (the UUID must be the selected server's actual instance):
+
+```json
+{
+  "serverUrl": "https://ours.example.net/base",
+  "endpoint": "https://ours.example.net/base/daemon",
+  "expectedInstanceId": "11111111-2222-3333-4444-555555555555",
+  "credentialPath": "/absolute/private/credential"
+}
+```
+
+`endpoint` is optional for the client resolver; when present it must exactly match
+`serverUrl + "/daemon"` after trailing-slash normalization. Older endpoint-only
+profiles must be migrated explicitly: supply the actual gateway URL, not a
+guessed address derived from a direct daemon port.
+
+```sh
+ours-install client --config /absolute/private/profile.json \
+  --integrations codex,claude-code
+```
+
+This imports the profile and issued credential into `~/.ours-client`. All new
+clients use that default without an environment export. A conflicting existing
+server instance is refused and retained; do not delete it to bypass that check.
+To change only the gateway address of the same server, prepare a private profile
+with the new `serverUrl` and matching `/daemon` endpoint, keep its actual
+`expectedInstanceId`, and run the same `ours-install client --config ...` command.
+The installer validates authenticated access before importing the new address;
+it preserves imported Fleet settings. New processes use the new address. A
+failed verification leaves the old selection intact. A different server UUID
+requires a separately planned migration, not an address edit.
+
+Changing the retained Docker public listening port in place is not currently
+supported. `--port 4050` above is for a fresh server. For an existing server,
+configure an administered reverse proxy to its gateway at the desired address,
+then use the same-instance client address procedure. Do not edit installation
+state or recreate containers with new identities to work around this limitation.
+Native server installations currently need a separately administered gateway;
+the integrated gateway setup above uses Docker (or supported Podman Compose).
+
+## Fleet and systemd
+
+For a new Fleet setup, save the linked JSON example as an absolute private file
+and run as the same user after importing the client profile:
+
+```sh
+ours-fleet init --settings /absolute/path/fleet-settings.json
+```
+
+If the installer already imported Fleet settings, reuse them explicitly:
+
+```sh
+ours-fleet init --settings "$HOME/.ours-client/fleet-settings.json"
+```
+
+These commands work without a terminal. A bare `ours-fleet init` is interactive.
+The installer also accepts `--fleet-settings /absolute/path/fleet-settings.json`
+and passes it to this same noninteractive path. Generated systemd and launchd services persist only the common
+profile path, not a service URL, port, or token. Lingering user services therefore
+use the same selection as CLI and MCP after logout/reboot. Detached Fleet task
+workers inherit the common profile and do not inherit legacy service selectors.
+
+`OURS_CONFIG` is an explicit override for the **whole client profile**. Use it only
+when all relevant clients intentionally share that same alternate file. It is
+not a per-service address override. For the normal setup, leave it unset.
+
+When migrating existing units, inspect `systemctl --user cat 'ours-fleet-agent@.service'`
+and any per-role drop-ins. Remove stale `OURS_PORT`, `OURS_STATE_DIR`,
+`OURS_API_TOKEN`, `OURS_DAEMON_ID` and Cowork-local overrides from their owning
+configuration. Regenerate Fleet units with `ours-fleet init --settings /absolute/path/fleet-settings.json`
+in the intended profile environment, then restart affected client roles only after approval.
+Already-running clients retain their current connection until restarted; editing
+a profile does not rebind running identities. Do not restart the server for a
+client-only profile correction.
+
+## Verify and diagnose
+
+```sh
+curl --fail http://127.0.0.1:4050/.well-known/ours
+ours config show --json
+ours identity list --json
+ours-fleet doctor
+ours-fleet room list
+```
+
+Discovery must advertise the gateway and expected instance. `ours config show`
+shows only connection metadata and a credential path, never the token. For a
+remote server use its exact prefix in the discovery URL. Test both daemon
+identity access and Cowork room listing: one succeeding does not prove the other.
+Check `command -v ours-mcp` and `ours-mcp version` as well as the MCP binary launched
+by the harness; Fleet can bundle a different MCP version than the global binary.
+
+Missing/unsafe profiles, mismatched instances, rejected credentials, HTTP errors
+and timeouts fail on the selected gateway. Fix that selection or service; do not
+add localhost/socket fallbacks. If a task reports `room_probe_unavailable`, check
+Cowork through the gateway. `control_unavailable` means Fleet could not query its
+local role supervisor after its room checks; inspect the role's supervisor and
+control channel separately. An active room alone does not establish agent readiness.

package/README.md

@@ -1,3 +1,19 @@
+## Install first, connect the App afterwards
+
+```sh
+ours-install --username alex --name Alex --surname Taylor --disable-fleet-agents-setup
+```
+
+This permanent command contains no tunnel credentials or enrollment expiry. On a terminal it asks for the remaining installation choices, including Docker, Podman or native packages. The username is local and has no global uniqueness check. A fresh root is named `<username>@<hostname>`; the optional `--hostname` defaults to the machine name. Messenger stores Name and Surname through its supported profile API. Retried setup retains root identities and existing Messenger profiles.
+
+`--disable-fleet-agents-setup` installs the Fleet CLI and saves the choice without opening its agent/model wizard or rewriting existing Fleet configuration. Configure agents in the App after device linking. Complete presets still work unattended; partial presets require a terminal and cannot use `OURS_ASSUME_YES`.
+
+The separate `ours-fleet setup-tunnel --file /private/setup-payload` step requires the matching Fleet follow-up release. Its private App payload remains scoped, signed-root-bound and expiring. Then run `ours-fleet link-device` and paste its private single-use code into the App. Do not put the expiring tunnel payload in the permanent installer command.
+
+Native packages currently provide server-only installation; full Fleet/App onboarding requires the supported gateway (Docker or Podman). The installer refuses unsupported native full-stack setup before changing anything. This PR does not add a native gateway or release unpublished Fleet commands.
+
+See [one-connection setup, localhost:4050 and systemd migration](GATEWAY_SETUP.md) for the gateway-only client workflow.
+
 # @ours.network/install — one installer for the whole stack
 
 Requires Node.js 22+ and npm. Install the selected release channel:
@@ -10,8 +26,8 @@ ours-install
 With no arguments, the wizard explains each step and offers keyboard choices.
 Use arrow keys and Enter to choose, and Space to select integrations. Recommended
 settings keep advanced ports and package overrides out of the usual flow. Text
-input is used for your name and explicitly customized paths or ports. Linux x64
-recommends native mode; macOS and Windows recommend Docker. On Windows run the
+input is used for your name and explicitly customized paths or ports. Docker is recommended for the integrated full-stack gateway on every platform;
+native packages remain available for server-only setup. On Windows run the
 installer inside WSL with Docker Desktop integration. This recommendation concerns
 packaging and isolation, not a guarantee that emulated x64 is faster on ARM Macs.
 
@@ -45,7 +61,7 @@ installers. `--integrations none` explicitly skips client integrations. Use
 Fleet's own wizard is available only in interactive setup; CLI Fleet setup requires
 its JSON settings file. Fleet stays stopped until you review and activate it.
 
-The server installs the daemon/SDK/CLI, main MCP, Telegram, Cowork and Messenger.
+The server installs the daemon/SDK/CLI, Telegram, Cowork and Messenger.
 It starts the daemon, preserves the existing Human identity (or creates it once),
 then starts its applications. Full-stack setup issues a separate local client
 credential and configures the selected Codex, Claude Code and Fleet integrations.
@@ -56,6 +72,28 @@ The installer embeds exact component versions and SHA-512 values for its release
 An existing server's retained release selects matching local clients. Secrets are
 read from protected files, and client setup never copies the daemon API master.
 
+## Runtime and client packages
+
+Server selections include `@ours.network/daemon`, whose `ours-daemon` binary owns
+runtime startup and service administration. Docker runs `ours-daemon serve`;
+native installations install its systemd/launchd service. Existing retained
+installations can still stop and restore their older CLI-owned runtime.
+
+Client selections contain the thin SDK and CLI, plus MCP when a harness needs
+it. They exclude the daemon and its native database/ADAPT dependencies. Fleet
+runs beside the harnesses on the client machine and calls the daemon HTTP API.
+Client commands report an unavailable server and never start one automatically.
+
+The checked-in source policy and packed installer retain the existing server
+release set (SDK `3.8.1-nightly.11`, CLI `2.8.1-nightly.9`, daemon
+`3.8.1-nightly.3`). The isolated host CLI uses published SDK
+`3.8.1-nightly.13` and CLI `2.8.1-nightly.11`, including the shared gateway
+profile resolver. `releases/nightly.json` binds both selections to verified
+SHA512 integrities. Gateway-only Fleet/MCP release adoption is still pending;
+see [GATEWAY_SETUP.md](GATEWAY_SETUP.md). Mixed or unselected nested ours
+versions remain rejected within each selected graph. An explicit `--sources`
+override remains available for development.
+
 ## Migrate an existing global installation
 
 The wizard detects the old `~/.ours/config.json` and offers to keep its identities,
@@ -137,8 +175,8 @@ native package acquisition, and reports completion only after service readiness.
 If a Docker service fails, the error includes its last 50 log lines (bounded in
 size) and a command to inspect the logs. A failed daemon prevents consumers from
 starting; a failed consumer does not prevent checks of unrelated consumers.
-Server runtime installation selects SDK/CLI, main MCP, Telegram, Cowork and
-Messenger. Main MCP is injected into the daemon, not started as a second daemon.
+Server runtime installation selects SDK/CLI, Telegram, Cowork and
+Messenger. MCP runs locally with the Codex and Claude Code plugins and calls the daemon API through the SDK.
 The daemon starts first; consumers are checked through their owning readiness
 interfaces. Messenger uses its existing identity prerequisite and never creates an
 identity. Its failure is reported after attempting unrelated consumers. Package
@@ -195,9 +233,9 @@ relative to the profile file. Select any nonempty subset of integrations; Fleet
 When Fleet settings are supplied, the installer passes them to Fleet's strict
 noninteractive `init --settings`; otherwise it opens Fleet's existing wizard.
 Fleet validates and publishes its own configuration. Client setup verifies the selected
-daemon and packaged OURS MCP before registering native integrations. It acquires
+authenticated daemon API before registering native integrations. It acquires
 only selected integration packages and their actual client dependencies. It does
-not install main MCP, administer daemon state or invoke Docker. Exact npm client
+not administer daemon state or invoke Docker. Codex and Claude Code include the local stdio MCP server as a dependency. Exact npm client
 installation needs no Python; Git source builds use the supplied source recipes
 and their build prerequisites. Normal native clients need neither Docker nor
 server maintenance tools.
@@ -213,7 +251,8 @@ an existing override and does not edit shell configuration or running sessions.
 Repeat with `ours-install client install` to reuse imported inputs and installed
 package records. Existing settings and Fleet-generated files are preserved. A
 prepared profile for the same endpoint/instance may supply a valid replacement
-issued token; another server is refused without changing the default. Invalid
+issued token; a different server instance is refused without changing the default. A verified
+new gateway address for the same instance updates the shared profile for new clients. Invalid
 server access is rejected before import. An acquisition or component failure
 reports incomplete setup and keeps the saved configuration for retry. Selected
 native integrations whose executable is unavailable are incomplete, not installed.
@@ -224,7 +263,7 @@ Interactive no-argument installation asks for package/Docker server mode, a
 prepared client profile, or `client`. Client setup offers the saved server when
 present. On first setup it asks for the server HTTP endpoint, issued-token file,
 source manifest and integration choices, obtains the instance UUID from
-`/selection`, displays it, then checks authenticated daemon and MCP access before
+`/.well-known/ours` at the gateway, displays it, then checks authenticated daemon API access before
 saving anything. No UUID must be entered manually. The 2.0 HTTP flow assumes the
 approved trusted same-host deployment; selection metadata is not cryptographic
 server authentication. Fleet collects missing setup answers through its own wizard.
@@ -281,3 +320,308 @@ maintenance reads both formats. Format2 is not readable by older maintenance too
 so this change does not promise executable downgrade support. Restore validates the
 original archive records unchanged, then writes markers for the active target runtime.
 Mixed/incomplete context and component record sets are refused before activation.
+
+### Retrying a Docker installation after a source-policy permission failure
+
+Setup verifies the selected Docker image before reusing it, including when the image
+already exists. If an older installer left a root-owned, mode-0600
+`/opt/ours/sources.json`, setup repairs only that image file's permissions and
+continues. The selected package bytes, build provenance, image execution settings,
+credentials and stored data are retained. The old materialized Dockerfile's known
+COPY instruction is also corrected for future builds. No manual image or volume
+deletion is required; repeat the original setup with the updated installer.
+
+The repair runs isolated verification containers without state mounts or network
+access. Other image verification failures stop setup without replacing the image.
+An interrupted repair can be retried, including after the image tag was replaced.
+
+### Remote clients over HTTPS
+
+A client may select an `https://` origin backed by a TLS reverse proxy. Keep the
+daemon listener private and configure the proxy separately with a certificate
+trusted by the client and matching the hostname. Node uses its normal trust
+store; a private CA may be supplied through `NODE_EXTRA_CA_CERTS` before starting
+the client. Certificate verification must remain enabled.
+
+The existing issued client credential works over either transport; changing the
+URL scheme does not require a new credential. Keep the server's master on the
+server. Forward `x-ours-api-token` and the `x-ours-*` session headers unchanged,
+and support streamed request/response bodies and long polling. Client requests
+refuse redirects, including HTTPS-to-HTTP redirects: configure the final HTTPS
+origin directly. UUID/capability checks still precede credential-bearing calls.
+
+This adds client HTTPS support, not an HTTPS daemon listener, certificate
+provisioning or automatic reverse-proxy configuration. Existing local HTTP and
+SSH-tunnel profiles continue to work.
+
+## One-URL Docker gateway
+
+New Docker installations use one loopback-published nginx port (default 3050).
+Clients import one `serverUrl`; their daemon endpoint is `<serverUrl>/daemon` and
+Fleet derives `<serverUrl>/cowork/management/rpc`. Cowork, Messenger and Telegram
+backend ports are internal only. Existing installations retain their prior layout
+on ordinary install/update. Select compatible releases before explicitly migrating:
+
+```sh
+ours-install server gateway-enable --state-dir /private/ours
+```
+
+Migration checks the installed Cowork, Messenger and Telegram capabilities before
+stopping services, verifies authenticated daemon and read-only Cowork management,
+and preserves the existing credential and client integration settings. Failure
+restores routing, client profile and prior service selection. An interrupted
+migration blocks other mutations: repeat `gateway-enable` to finish rollback,
+then run it again to attempt migration. The private `gateway-transition.json`
+retains recovery state until rollback or migration completes. Back up the whole
+installation using the normal server backup procedure before maintenance.
+
+For a nested external URL, pass `--server-url https://ours.example/base` during
+Docker install or `gateway-enable`. This sets browser origin and path configuration;
+it does **not** publish a public listener, provide TLS, or install external
+credentials. Configure the authenticated entry first and retain the `/base` path
+when proxying. A compatible release must contain these capabilities:
+`cowork.http-management-v1`, `messenger.gateway-prefix-v1`, and
+`telegram.gateway-listener-v1`. Older releases are rejected without enabling the
+new listener; no package version is silently substituted.
+
+### Notifications
+
+When the selected release includes `@ours.network/notifications`, gateway
+installations run it inside the Messenger container, under one supervisor with
+Messenger: a signal stops both, and either one exiting stops the container so
+its normal restart recovers both. It publishes no host port. The gateway routes
+`<serverUrl>/notifications/` to it after the same daemon credential check as
+Telegram, and the service's adapter checks that credential again before acting
+as the installation owner. Browser cookies, origins and fetch metadata are
+removed. Messenger produces message notifications over loopback.
+
+`prepare` creates the private configuration once in
+`storage/state/notifications/config.json`: the owner token, separate Fleet and
+Messenger producer tokens, and VAPID keys. Later runs only validate it; rotating
+the owner token or VAPID keys would orphan every browser subscription, so a
+differing configuration is refused rather than rewritten. Back it up with the
+rest of the server state. A local client setup binds the Fleet producer token
+to this server in `~/.ours-client/notifications-producer.json`; Fleet then sends
+agent completions through `<serverUrl>/notifications/`. Remote clients and
+native installations do not produce notifications. The gateway discovery
+document is unchanged, so existing clients keep accepting the server. A
+retained source policy without the package keeps working without notifications.
+
+An existing complete installation gains them with its normal update, which
+prepares the credentials after activating the new runtime and hands the Fleet
+producer credential to the local client, then a web-only Fleet restart (agents
+keep running):
+
+```sh
+ours-install all update --mode docker --state-dir /private/ours --identity-name "Your Name" --integrations codex,fleet --fleet-settings /private/fleet.json --compatible
+ours-fleet web restart
+```
+
+### Authenticated external entry
+
+Messenger has no application authentication. Loopback access trusts local users;
+never forward this gateway publicly without authentication. All applications on
+this origin share one trust boundary: scripts or XSS in any application can make
+requests to the others. Cowork's entered server credential grants operator room
+administration and stays in memory until reload. Path prefixes do not isolate
+applications. Only expose this origin to trusted operators.
+
+A supported external entry is nginx TLS plus HTTP Basic authentication for browser
+paths, with machine paths left to their existing server-token checks. Create the
+password file using an interactive `htpasswd` prompt and make it readable by the
+proxy worker. Use real certificates and the matching `--server-url`. The inner
+gateway remains bound to `127.0.0.1:3050`; neither backend ports nor the inner
+listener should be externally forwarded. Example for `/base`:
+
+```nginx
+# In http {}:
+map $http_upgrade $ours_connection { default upgrade; '' close; }
+server {
+    listen 443 ssl;
+    server_name ours.example;
+    ssl_certificate /private/tls/fullchain.pem;
+    ssl_certificate_key /private/tls/key.pem;
+    auth_basic "ours operators";
+    auth_basic_user_file /private/ours-users;
+    access_log off;
+    proxy_set_header Host $http_host;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection $ours_connection;
+    proxy_http_version 1.1;
+    proxy_read_timeout 300s;
+    proxy_buffering off;
+    location = /base/.well-known/ours { auth_basic off; proxy_pass http://127.0.0.1:3050; }
+    location /base/daemon/ { auth_basic off; proxy_pass http://127.0.0.1:3050; }
+    location = /base/cowork/management/rpc { auth_basic off; proxy_pass http://127.0.0.1:3050; }
+    location /base/tg-connector/ { auth_basic off; proxy_pass http://127.0.0.1:3050; }
+    location /base/ { proxy_pass http://127.0.0.1:3050; }
+    location / { return 404; }
+}
+```
+
+Browser requests include same-origin proxy credentials. Fleet/SDK use the issued
+`X-Ours-Api-Token`, require no browser login, and reject redirects. An SSH tunnel
+to the loopback gateway is another private transport option, but every client must
+establish its own tunnel and use a URL/origin matching that tunnel; it is not
+automatic remote access. Do not treat a token entered in Cowork as Messenger auth.
+
+Publish compatible Cowork, Messenger, Telegram and Fleet artifacts before enabling
+gateway defaults in a qualified installer release. Gateway client setup acquires
+and checks Fleet before activating the managed profile or publishing native
+commands. Migration also checks the installed `ours-fleet version --json`
+capability before stopping services when the selected managed profile includes
+Fleet. Upgrade that executable first. The gate does not inventory differently pinned
+running Fleet instances or remote clients: upgrade every client using this server
+to a compatible Fleet release before cutover.
+
+### Cross-repository gateway qualification
+
+Build Cowork, Fleet, Messenger and Telegram checkouts with their locked dependencies.
+The real-service test uses disposable local daemon state, a local test broker,
+nginx Docker containers and Chromium; it never uses installed identities or tokens.
+It requires Linux Docker host networking and `openssl`. Set:
+
+```sh
+OURS_TEST_GATEWAY_SERVICES=1 \
+OURS_TEST_COWORK_ROOT=/checkouts/ours-cowork \
+OURS_TEST_FLEET_ROOT=/checkouts/ours-fleet \
+OURS_TEST_MESSENGER_ROOT=/checkouts/ours-messenger-server \
+OURS_TEST_TELEGRAM_ROOT=/checkouts/ours-tg-connector \
+OURS_TEST_BROWSER=/opt/google/chrome/chrome \
+node --test packages/installer/test/gateway-services.test.mjs
+```
+
+Run `OURS_TEST_DOCKER=1 node --test packages/installer/test/gateway-docker.test.mjs`
+separately for Compose port isolation with a client container. That routing test
+uses echo upstreams; the real-service test covers Fleet room operations, browser
+paths, external authentication and Messenger WebSocket access. Neither test is
+cross-platform Docker Desktop qualification or a live deployment test.
+
+### Rootless Podman (qualification in progress)
+
+Container installations can select a local Linux rootless backend explicitly:
+
+```sh
+export PODMAN_COMPOSE_PROVIDER=/absolute/path/to/docker-compose
+ours-install server install --mode docker --container-engine podman \
+  --state-dir "$HOME/.ours-server-podman" --identity-name "Your Name"
+```
+
+`mode: docker` remains the legacy container-layout name. `containerEngine` and
+`containerBinding` retain Podman, the invoking UID, native storage paths, socket
+and standalone Compose provider, plus the UID/GID mapping fingerprint. Records without `containerEngine` continue to
+use Docker. Package/client installs reject the engine option. Existing records
+cannot change engines through a flag or ambient connection change; automatic
+Docker-to-Podman data migration is not provided. Legacy local-daemon migration
+(`--migrate-from`) to Podman is also unsupported and is refused before source
+shutdown or managed CLI publication, including migration retries. Use a fresh
+Podman installation, or migrate the legacy daemon with Docker/packages.
+
+Podman uses its native build command, with the same resolved Compose build
+context, target, architecture, arguments and secret references, followed by
+Compose `--no-build` startup. It does not require the Docker CLI or daemon.
+The selected standalone Docker Compose provider must be version 2.35 or newer;
+version checks do not replace the behavioral capability probe. `podman-compose`
+is not an interchangeable provider for this implementation. Secrets sourced
+from environment variables use Podman's native build-secret mechanism, never
+build arguments or temporary copies.
+
+Prerequisites include a working rootless API socket, sufficient subordinate
+UID/GID mappings, and native volume-subpath isolation. Before setup/start, an
+isolated disposable project tests Compose `!reset`, health waiting, JSON status,
+service DNS, private UID-1000 storage and subpath isolation. A failed check stops
+installation rather than substituting the whole volume. Existing volumes must
+have this installation's project and volume labels. Docker contexts, unrelated
+containers and host directory ownership are not changed.
+
+Server boot recovery requires an enabled user `podman.socket`, an enabled
+`podman-restart.service` using `--filter should-start-on-boot=true`, and user
+linger. The standard user-service environment/default socket must select the
+same storage; custom XDG paths and sockets are rejected for server startup.
+The installer diagnoses missing prerequisites and never runs hidden sudo or
+rewrites the vendor unit. Long-running Podman services get `unless-stopped`;
+administration jobs do not. Stop/status remain available when boot prerequisites
+are missing, provided the retained backend is accessible. Runtime-only test
+harnesses may select a separate local socket with `OURS_PODMAN_SOCKET`; its
+storage must match native Podman and the selection cannot change afterward.
+
+Gateway images read and validate IPv4/IPv6 nameservers from their container at
+startup. Only the resolver placeholder is replaced; nginx variables and existing
+authentication/routes remain intact. UID 101, read-only rootfs, dropped
+capabilities and tmpfs are retained. Setup and start verify authenticated
+upstream requests in addition to liveness.
+
+This change is **not yet a fully qualified server-support release**. Debian's
+Podman 5.4.2 with Compose 5.5.1 failed subpath isolation and has incompatible boot
+recovery semantics. Podman 6.1.2 passed the isolated capability probe on native
+Linux amd64; production and prerelease-source builds, service lifecycle, rebuild and scoped maintenance also passed. See [validation evidence](ROOTLESS_PODMAN_VALIDATION.md). The full public installer/maintenance matrix,
+SELinux Enforcing, logout/reboot, explicit-stop recovery, and Docker regression
+matrix must all be recorded before declaring a supported engine/provider pair.
+The supplied ARM VM results are historical feasibility evidence, not this
+release's qualification.
+
+Opt-in gateway fixture (isolated project, only owned resources removed):
+
+```sh
+OURS_TEST_DOCKER=1 node --test test/gateway-docker.test.mjs
+PODMAN_COMPOSE_PROVIDER=/absolute/path/to/docker-compose \
+  OURS_TEST_PODMAN=1 node --test test/gateway-docker.test.mjs
+```
+
+## Account workspace enrollment (task build)
+
+The unmerged account onboarding feature requires matching reviewed installer,
+Fleet and Messenger task builds. Do not advertise it as available in `@latest`.
+Use an owned private directory and a 0600 downloaded payload:
+
+```sh
+node /absolute/task-ours-network/packages/installer/install.mjs \
+  --setup-workspace-file /absolute/private/workspace.payload \
+  --workspace-fleet-bin /absolute/task-ours-fleet/dist/cli.js \
+  --sources /absolute/private/task-sources.json
+```
+
+The wrapper defaults fresh hosts to the full Docker stack and retains existing
+Human roots through the installed SDK with exact instance/private credential
+selection. For an existing supported gateway add `--scope client --config` with
+its private profile. It clears competing inherited daemon selectors before Fleet
+initialization and enrollment; it never copies a browser device bearer to the
+account server. A private stdin payload is also accepted by `--setup-workspace -`.
+Encoding is not encryption; command arguments can enter history/process listings.
+Cloudflare management tokens are forbidden in these payloads.
+
+Docker and `cloudflared` are required for the fresh workflow. Supply a complete
+`--fleet-settings` JSON for noninteractive Fleet initialization, or answer its
+terminal prompts. Dry-run never initializes or enrolls Fleet. Read the matching
+ours-app `server/DEPLOYMENT.md` for exact task source-policy generation, external
+Google/Cloudflare prerequisites and account-server setup. On uncertain enrollment
+check account status before requesting a new payload; do not reset identities or
+replay a consumed invitation.
+
+Workspace setup accepts exactly https://app.ours.network and the controlled test
+account origin https://app.ours-tunnel.com. To move an existing same workspace to
+the other origin, obtain a fresh payload from the moved account server and add
+`--workspace-migrate-app-origin`. Fleet verifies the signed binding receipt before
+changing local origin trust, preserves identities/config/device records, and
+restarts the runtime. An implicit origin change is rejected. Browser account
+cookies/device IndexedDB must be linked anew on the new origin. See the app
+server/DEPLOYMENT.md switching procedure.
+
+Workspace setup automatically reuses the saved managed gateway profile (or explicit `--config`/`OURS_CONFIG`), including a host with a non-default server state directory. It does not reinstall server/client state, create a root, or initialize an existing Fleet configuration. It requires Fleet capability `workspace.enroll.preserve-profile-v1` and passes `--preserve-profile`; Fleet requires the matching Messenger capability before posting signed enrollment. Hosts running older Messenger must first update that host service through its supported installer lifecycle; this wrapper never guesses or replaces its server directory. After Owner releases Messenger/Fleet/installer, app bootstrap pins must be updated before removing the preview guard.
+
+### Private-context Docker script permissions
+
+Fresh image builds explicitly make non-secret maintenance/runtime scripts readable by the container user even when the host build context was copied under umask077. Host scripts, selected source policy and state retain their private permissions.
+
+For a pending installation using an older image, run the corrected installer against the same pending workspace. It recognizes older shipped script COPY instructions combined with private host script modes, updates those image COPY modes and rebuilds the daemon image from the retained source selection. It leaves host data and enrollment state intact and qualifies the rebuilt image before preparing services. A private retry marker retains the rebuild requirement after interruption; it is removed only after verification succeeds. This rebuild resolves third-party transitive dependencies using the existing testing-delivery rules; selected Ours versions and integrity remain release-checked. It is not a byte-identical image permission-layer repair.
+
+Fresh server setup checks its loopback daemon, Cowork and Messenger ports before
+writing the installation configuration. Occupied implicit defaults advance to a
+free port, skipping reserved sibling ports; the selected values are saved in the
+installation record and used by native/container services, gateway and client
+profile generation. An explicitly requested occupied port fails with a diagnostic.
+Existing installation records keep their ports and identities. A listener acquired
+by another process after preflight still causes startup to fail safely; no foreign
+process is stopped and no retained installation is silently moved.
+
+Workspace setup pins Fleet `1.2.0-nightly.39` with its recorded registry integrity. This release includes first-time Fleet setup through the host API for the account App, direct App access to the workspace services with the device credential, separate `ours-fleet setup-tunnel` and `ours-fleet link-device` commands, host prerequisite checks before the one-time workspace proof (`setup-tunnel --check`), `setup-tunnel --resume` to finish a setup that stopped after the host saved its private pending setup record (not when the proof's answer was lost, or after the setup window expired with an unconfirmed non-default port), and persists the available Fleet loopback port used by the workspace tunnel. It also accepts a setup-generated configuration left behind after the host enrollment state was removed, runs the host Codex when it is at least as new as the packaged one, offers only the Codex models the signed-in account can use, and removes the temporary setup contact after confirmation. Fleet serves no pages and opens no browser: every screen is in the App. Fleet also serves the workspace notification routes, produces notifications through the server gateway with the imported producer credential, and defaults agent wakes to `monitor.interrupt: after_tool` (Hermes: no interrupt). Existing installation identities and configured ports remain retained; a retained-port collision fails safely.