docs/maintenance.md
Rama main · réplica de lectura del repositorio original.
# Refresh, upgrade, rollback, and uninstall
Relmio installs ChatGPT plan connections through the local browser wizard.
The wizard owns SIWC registration, protected storage, model discovery, and the
reviewed local/VPS sidecar lifecycle. Do not use older instructions that copy
`auth.json` or run `openai-oauth` directly.
## Reauthorize a ChatGPT registration
Open the local wizard with `relmio open` or start it with:
```bash
npx --yes --ignore-scripts relmio@latest
```
Select the intended saved registration and choose **Sign in again** or
**Allow ChatGPT plan use** as shown. Reauthorization uses the same issued client
and verified subject. A new registration remains separate even when it has the
same email. If sign-in succeeds without the ChatGPT plan scope, identity stays
connected but model access remains disabled.
If plan use was paused locally, re-enable it only if the selected registration
still has the provider grant. The first-use plan notice must be acknowledged
before model access. **Manage usage** opens ChatGPT's usage settings.
## Install or manage the n8n sidecar
The selected n8n container and Docker network must already exist. The wizard
reviews both, requires separate consent for background workflow use, and asks
for final confirmation before a sidecar write. It does not change n8n's
credentials, Compose configuration, image, or lifecycle.
Installation generates a bearer for the private Relmio sidecar, displays it
once, and stores only its SHA-256 verifier in Compose. Enter the bearer
manually in n8n. It authorizes the sidecar, not OpenAI. The sidecar publishes
no host port.
Local and VPS installs bind the selected registration to a destination host ID
and runtime. The review also binds the exact n8n container and network IDs;
the VPS installer checks them again before its first write and before the
transfer, and a changed ID requires a new review. After a VPS install
completes, status and sign-out need only the same SSH host identity and Docker
network ID, so recreating n8n or changing the SSH login method does not block
them. The wizard initializes the
destination before freezing the source for transfer. The destination becomes
the sole refresh owner after it returns an attested receipt; only then are
source tokens cleared. If transfer or receipt is uncertain, leave the sender
frozen and use the reviewed recovery below. Do not restore an old token
backup, repeat the handoff blindly, or activate both copies.
### Resume or reconcile an interrupted install
If an install stops partway, status shows it as staged. Select the account,
choose the resume action, review the plan, and confirm it. Relmio continues
the same installation without deleting data or starting a second refresh
writer. A same-account resume uses the account's current state, so turning
plan use on or off or a token refresh does not block it. Resuming after the
session already moved replaces the one-time key.
If the destination accepted the session but the sender lost the
acknowledgment, the account stays handoff-pending. Choose the reconcile
action, review it, and confirm within five minutes. Relmio reads the
destination's identity-bound receipt and finishes the handoff. Without a
receipt the sender stays frozen and needs a fresh sign-in; old tokens are
never restored. A transport failure reports an unknown remote outcome. A
different account can take over only after a confirmed "not accepted"
result; Relmio refuses if the original receipt appears, and on a VPS while a
one-off sidecar helper container is still present.
If ownership moved but a later finishing step failed, the result is partial.
It still shows the one-time key once, with a warning not to use it until the
reported issue is resolved. Relmio never restarts an old writer
automatically.
The SIWC Terms' local/user-controlled token-storage language and OpenAI's
self-hosted VM guide do not resolve persistent remote VM storage. This guide
describes Relmio's implementation, not provider approval for a VPS.
## Migrate a local credential-copy installation
An older `auth.json` credential-copy bridge is not a SIWC registration and is
never imported into the new runtime. When the local wizard detects an owned
legacy target, its separate migration review requires a fresh SIWC sign-in,
separate migration consent, and final confirmation of the exact target.
Only after confirmation does Relmio stop the attested old service. Its old
credential and workspace volumes remain offline; the replacement uses a new
registration/runtime and a new local bearer. Old history and tokens are not
merged. If any migration or stop result is uncertain, the old writer stays
stopped, retained volumes are left for inspection, and Relmio does not
automatically resume, roll back, or delete them. Do not manually copy tokens or
remove the retained volumes.
This describes the local migration path only. VPS legacy migration has its own
reviewed state and is not provider-approved by these controls. The current
source check records the separate, unresolved VPS token-storage question.
## Sign out or disable plan use on an installed target
Choose **Manage account** for the installed Codex or n8n target. Relmio
re-attests the owned installation and stops the exact service before changing
the selected registration. If the process cannot be confirmed stopped, the
account operation does not proceed.
Sign-out attempts provider revocation and clears local access, refresh, and ID
tokens. The account mapping remains. The result distinguishes confirmed,
unconfirmed, and not-applicable revocation. A refresh-uncertain session remains
unconfirmed even if OpenAI returns HTTP 200, because the refresh-token family
may have rotated outside the known record. If unconfirmed, disconnect Relmio
in ChatGPT settings; local cleanup is not proof of remote revocation or
provider-side deletion.
## Replace the account on an installed target
Relmio does not silently swap an installed target to another account. First
sign out or disable plan use through **Manage account**; Relmio attests and
stops only that owned service. A replacement plan is available only after the
old target is confirmed signed out and stopped. Select a new independently
authorized SIWC registration, review the exact replacement, and confirm it
separately.
The old registration mapping and any Codex history or credential volumes remain
preserved separately and offline; only the new registration is activated after
review. Relmio does not transfer or merge token/history state or combine
accounts by email. If replacement state is uncertain, inspect the stopped
target and retained data; Relmio does not restore the old account automatically.
## Recover a request or transfer
- Identity-only account: request the plan grant separately in ChatGPT.
- Usage-limit error: open **Manage usage**; do not rotate accounts or switch
billing.
- **Model-inference 503 or interrupted stream:** keep the same registration
and follow the shown retry-later action. A partial answer is not success.
- **Token discovery fails before refresh:** no refresh POST was sent, so the
session is unchanged; retry later as shown.
- **Refresh POST returns 503 `temporarily_unavailable`:** the pre-refresh
session is restored and Relmio reports retry-later. This assumes OpenAI did
not rotate the refresh token, which OpenAI does not document.
- **Refresh POST returns another error, or its network outcome is
uncertain:** plan use is frozen before the POST. Protected token bytes may
remain, but the old refresh token is never retried. Complete a fresh SIWC
sign-in for the same registration before model use.
- **Refresh response cannot be verified:** replacement tokens remain frozen
with no access lease until successful authentication. `invalid_grant` clears
unusable tokens and requires reauthorization.
- **Unconfirmed revocation after refresh uncertainty:** a successful remote
revoke response does not clear the uncertainty; disconnect Relmio in ChatGPT
settings.
- Unsupported capability or parameter: correct the request; do not retry it
unchanged or expect a fallback.
- Unresolved handoff: retain the frozen source and use the reviewed resume or
reconcile action above.
## Update the runtime
Install a newer Relmio package to update the wizard. Existing sidecars are
separate deployments; use the offered ownership-attested maintenance action
and review its target and plan before confirming. A package upgrade alone does
not replace a running sidecar. Do not apply old Dockerfile or Compose snippets
from the former credential-copy guide to an existing installation.
For local endpoints, select the exact target and use the dashboard's reviewed
management action. For VPS, confirm the SSH host fingerprint before
authentication, review the selected server identity, and give a separate
final confirmation for remote writes. Never publish port `10531` or change
the existing n8n service to recover the sidecar. To rebuild an installed VPS
ChatGPT sidecar from the current version, follow
[Update the installed sidecar](vps-and-n8n.md#update-the-installed-sidecar).
## Recheck OpenAI sources
For each implementation or documentation update, fetch current official
identity, SIWC plan-use, model/limitation/error, applicable Terms, and privacy
sources. Compare the exact code path with the sources. Record what Relmio
reads, stores, transmits, and logs; scopes; data recipients; and unresolved
retention or provider requirements. Keep identity, separately granted plan
permission, and model/host capability as separate checks.
The current review is
[openai-source-check-2026-10-05.md](openai-source-check-2026-10-05.md).
Earlier dated source checks are historical implementation records. None is
legal approval, and issue #97 assigns privacy/legal copy to the owner and
counsel.
## Updating or rolling back AI Assistant companion images
The AI Assistant companion has no automatic remote image upgrade. Relmio never
edits the existing n8n Compose file, image, or environment, and never directly
mutates n8n as part of a companion update or rollback.
Maintainers must treat the Sandbox Service API, privileged runner, and nested
sandbox image as one compatibility unit. Before changing
`ASSISTANT_COMPANION_IMAGES` in `src/domain/assistant-templates.js`:
1. Review the official [n8n Sandbox Service release notes and source](https://github.com/n8n-io/n8n-sandbox-service), its [API](https://github.com/n8n-io/n8n-sandbox-service/pkgs/container/n8n-sandbox-service-api), [runner](https://github.com/n8n-io/n8n-sandbox-service/pkgs/container/n8n-sandbox-service-runner-dind), and [nested sandbox](https://github.com/n8n-io/n8n-sandbox-service/pkgs/container/n8n-sandbox-service-sandbox) package registries, plus the [SearXNG source](https://github.com/searxng/searxng) and [SearXNG package registry](https://github.com/searxng/searxng/pkgs/container/searxng).
2. For every candidate, verify the reviewed tag resolves to the intended OCI
**index** digest and the required Linux platforms. Record a full immutable
`tag@sha256:<digest>` reference; never substitute `latest`, `stable`, a
tag-only reference, or a digest-only reference.
Inspect each numbered or source-revision tag with the same command pattern:
```bash
docker buildx imagetools inspect \
ghcr.io/UPSTREAM/IMAGE:REVIEWED_VERSION_TAG
```
Record the top-level `Digest` and required Linux platform entries from that
output. Then repeat the inspection with the proposed full
`tag@sha256:<digest>` reference and require the same top-level digest. This
is maintainer evidence gathering only; it does not authorize an update to a
running companion.
3. Update only the exact source constants, add or update a generated-Compose
regression, and run these local release gates from the repository root:
```bash
node --test \
--test-name-pattern="immutable|floating|pinned" \
test/assistant.test.js
npm run check
npm audit --audit-level=high
npm pack --dry-run
npm --prefix web run lint
npm --prefix web run typecheck
npm --prefix web run build:vercel
npm --prefix web test
npm --prefix web audit --audit-level=high
```
Obtain a fresh security review of the exact change set after every fix.
Release only after all gates pass.
For an already managed companion, the administrator updates Relmio locally,
reconnects and completes host-key confirmation plus read-only discovery, then
reviews the exact companion-only plan. Keep the recorded SearXNG selection
unless intentionally changing it, provide the separate final confirmation, and
then verify that only ownership-labeled companion resources changed, there are
no host-published ports, and n8n remains healthy. Do not treat a local Relmio
update as remote-upgrade authorization.
To roll back, restore the previously reviewed complete `tag@sha256` set through
the same locally updated Relmio build and separately confirmed managed update.
Repeat read-only discovery, exact-plan review, final confirmation, and the
post-update checks above. Never roll back by pulling a moving tag or by editing,
restarting, recreating, or otherwise mutating n8n.
## If n8n is upgraded
This project does not alter the n8n image. A normal n8n image update can still
change node behavior or Docker networks.
After an n8n upgrade:
1. Confirm n8n is healthy.
2. Confirm its network name still matches the sidecar network.
3. Retry the OpenAI credential.
4. Verify one simple OpenAI Chat Model prompt.
If the network name changed, rerun the wizard and select the new shared
network. Do not edit or rebuild n8n merely to repair the sidecar.
## VPS build state and operation-lock recovery
After final confirmation, builds can create temporary root-only mode-`0700`
Buildx client state at these reviewed paths:
- Model install/retry:
`/docker/n8n-openai-oauth/.local-model-operation.lock/buildx`.
- SuperGrok install/sign-in/sign-out:
`/docker/n8n-openai-oauth/.supergrok-operation.lock/buildx`.
- Claude install/replace:
`/docker/n8n-openai-oauth/.claude-operation.lock/buildx`.
- OpenAI bridge install/update:
`/docker/n8n-openai-oauth/.openai-oauth-operation.lock/buildx`.
State is created lazily only for a build-capable call; an already-cached retry
needing no build, status and removal do not create it. Compose `up` is generated
with `--no-build`. SuperGrok credential-action `run` can still build, which is
why its reviewed sign-in/sign-out actions also need confinement.
Successful cleanup removes verified owned temporary state before releasing
the matching lock. If an SSH command or SFTP upload has started but its
completion cannot be confirmed (for example, the connection drops before a
verified exit status), the remote outcome is unknown. Relmio skips cleanup and
retains the operation lock and any Buildx state for administrator inspection,
even if a later SSH connection responds. A partial managed model file may
remain after an interrupted SFTP transfer. A verified nonzero exit is a known
failure and follows the ordinary reviewed cleanup path.
Every SSH command has a finite deadline: 45 minutes by default, 30 minutes for
an image build, 2 minutes for SIWC handoff acceptance, and 5 minutes for
publishing a managed file. A deadline closes that command and reports an
unknown remote outcome; Relmio does not retry it. SIWC managed files are
published through an exclusive temporary file and an atomic rename under
`/docker/n8n-openai-oauth`, never by truncating an existing file. If the
outcome of that publication is unknown, the temporary file may remain for
inspection.
A lost response while acquiring the lock also requires inspection rather than
assuming no lock exists. Do not treat the error as proof that the remote action
did not run, and do not automatically retry, remove the lock, or clear state.
Cleanup rejects symlinks, hard links, ownership, inode or mount ambiguity.
Interruption during cleanup or an uncertain cleanup result can leave the lock
and a partially cleaned state tree. If the main action also failed, that
original failure is preserved; do not assume every cleanup error means the
main action never ran.
Do **not** delete a lock blindly, recursively clear its directory, run Compose
`down`, prune Docker resources or clear model weights as an automatic repair.
An administrator must first establish that no operation still uses the lock,
inspect the exact recorded ownership and remaining state, and decide any
target-specific recovery separately. A similarly named or replaced tree is
not permission to remove it. Relmio's build-state cleanup never removes n8n
or model-cache data and does not copy, move or print registry credentials.
The managed OAuth bridge also owns a guarded `Dockerfile.dockerignore` that
allows only its Dockerfile and runtime source into the build context. A
preexisting unknown ignore file is a refusal, not an automatic overwrite.
Do not delete that file or include `auth`/sibling installations in the build
context to make a failed build proceed.
## Linux local-model acceptance harness
`dev/local-model-linux/harness.mjs` is an interactive maintainer tool for a
**separate disposable n8n fixture**, not an installer for your existing n8n.
Use a fresh dedicated checkout on a human-approved real Linux host with Node.js
24+, local rootful Docker Engine, Docker Compose 2.17+, the production model
resource budget and outbound image/model-registry access. It refuses Darwin,
remote Docker overrides/contexts and unsupported engines; it never starts
Docker Desktop or uses a production n8n instance.
### A. Ready-runtime recovery
Run from the repository root, **one command at a time**, reading the result and
any exact-target confirmation before continuing:
```sh
node dev/local-model-linux/harness.mjs preflight
node dev/local-model-linux/harness.mjs fixture
node dev/local-model-linux/harness.mjs review
node dev/local-model-linux/harness.mjs install
node dev/local-model-linux/harness.mjs wait
node dev/local-model-linux/harness.mjs reconnect
node dev/local-model-linux/harness.mjs workflow
node dev/local-model-linux/harness.mjs fault
node dev/local-model-linux/harness.mjs retry
node dev/local-model-linux/harness.mjs workflow
```
The fixture step creates its own n8n container/data volume and permits normal
n8n database initialization only after target-specific approval. The model
step uses the real production local-model service with `qwen3:0.6b`, isolated
Relmio home/state, a fresh installation ID and a private bridge with registry
egress. Nothing publishes a host port or mounts the Docker socket. The harness
does not request OAuth/API credentials or fabricate an n8n API key.
Resource review is not advertised as mutation-free: the production disk-space
probe runs a named read-only, no-network, no-mount helper and removes that
helper only after the exact **RUN-AND-REMOVE-READONLY-DISK-PROBE** approval.
Install, retry, the first workflow import and every workflow execution have
their own target-specific confirmations.
Each command is a fresh process. `reconnect` must reconstruct status without
repair/restart. The workflow imports and runs only a fixed Manual Trigger →
HTTP Request workflow in the disposable fixture through its documented n8n
CLI. It validates the actual Chat Completions result, not merely CLI exit
status. This CLI activity is a fixture-only exception: the managed installer
still never executes inside or changes your existing n8n.
The single `fault` stops only the owned model runtime after exact confirmation.
The following reviewed `retry` must preserve the cache file hashes, model
digest, cache-volume creation identity and runtime identity; it creates a new
acquisition operation. The second workflow demonstrates post-recovery
inference. Fixture n8n container/image/start/restart identities and its
network/data-volume identity must remain unchanged throughout. Cache
retention does not establish byte-offset download resumption.
### B. Interrupted cold download
Use a **different fresh checkout and fixture** from scenario A. Do not delete
an installed model merely to manufacture a cold cache:
```sh
node dev/local-model-linux/harness.mjs preflight
node dev/local-model-linux/harness.mjs fixture
node dev/local-model-linux/harness.mjs install-midpull
node dev/local-model-linux/harness.mjs reconnect
node dev/local-model-linux/harness.mjs retry
node dev/local-model-linux/harness.mjs workflow
```
`install-midpull` starts the real cold install, waits for observed positive
partial acquisition progress, and displays the exact runtime, operation and
cache identities for human approval. It rechecks that the download is still
partial after approval before stopping only that model runtime. If it
finishes too quickly or the stopped cache is already complete, the result is
**NOT-RUN**, not an interrupted-download success. Cache remains intact; there
is no automatic redownload or destructive retry to force the scenario.
The harness separately asks to create and start an exact owner-labelled,
no-network, read-only cache inspector. It requires real nonempty partial
blobs without a completed model manifest, records SHA-256 inventories, and
retains the inspector. Before the first production retry restarts the writer,
it asks again to start that inspector and requires the partial inventory and
cache/runtime identities to be unchanged. Production retry must then acquire
the catalog-approved model and pass the actual n8n workflow.
If the original partial-observation command was interrupted, the separate
`node dev/local-model-linux/harness.mjs interrupt-pull` command can reconnect
to that stage; it does not inject a second fault after a recorded interruption.
Do not use it to relabel ready-runtime recovery as a cold-download test.
Inspector lifecycle has no separate CLI command: its exact-target prompts
are part of `install-midpull`/`interrupt-pull`, `retry` and `remove-model`.
### Evidence and deliberate removal
Removal is **not automatic**. Only when you have reviewed the exact owned
targets and deliberately want to delete them, run these individually and
answer their separate interactive prompts:
```sh
node dev/local-model-linux/harness.mjs remove-model
node dev/local-model-linux/harness.mjs teardown
```
The first separately confirms/removes any retained cache inspector before
independently reviewing and deleting the attested model/cache. The second
deletes only the attested disposable fixture resources, including its n8n data.
Neither is an automatic recommendation to clean up a failed run.
Neither is a generic `docker compose down`, prune command, failure handler or cleanup trap.
There is no `--yes` or CI/environment approval bypass. Headless invocations
must hand off to a human TTY. Failure or interruption preserves resources and
evidence; an uncertain lock requires inspection, not automatic removal.
Owner-only evidence is recorded in
`dev/local-model-linux/.runtime/evidence.jsonl` with bounded output and file
size. It contains resource identities, progress and the fixed-prompt result;
review it before sharing. After approved teardown, evidence, owner marker,
isolated home and shared downloaded images intentionally remain. Use a
separate checkout for another cold run rather than deleting evidence or
reusing the marker as if the run were new.
Scenario A records `readyRuntimeRecoveryComplete`. Scenario B can record
`interruptedColdDownloadVerified:true` only after genuine partial observation,
retention before restart, reconnect, successful production retry/workflow and
separately approved removal. Its `byteOffsetResumeClaimed:false` is deliberate:
preserving partial bytes plus successful recovery does not measure resumed
network byte offsets. A failed/NOT-RUN scenario can be cleaned up after its own
approval but must not be reported as acceptance success.
**Evidence limits:** implementation-time checks observed CLI help, the
real-Linux preflight refusal on Darwin, injected guard/payload behavior and a
bounded cache-inventory process over synthetic local files. They did not run
a live Linux Docker model download, n8n workflow, interrupted pull,
SSH/provider deployment or Windows agent session. No hosted CI workflow
claims this proof: an early dispatch flag cannot approve resource identities
generated later. Full acceptance requires the separately authorized
interactive Linux runs and their recorded results.
## Roll back or disable the bridge
Stop and remove only the sidecar container:
```bash
docker compose \
--project-name n8n-openai-oauth \
--file /docker/n8n-openai-oauth/docker-compose.yml \
down
```
The files and OAuth credential remain available for recovery. n8n remains
running.
In n8n, disable workflows that depend on the bridge or replace their OpenAI
credential.
## Recoverable uninstall
First run the sidecar-only `down` command above. Then move the project directory
to a dated backup:
```bash
mv /docker/n8n-openai-oauth \
"/docker/n8n-openai-oauth.disabled-$(date +%Y%m%d-%H%M%S)"
```
This is recoverable: move the directory back if needed. After confirming the
backup is no longer required, remove it through your normal VPS backup and
retention process.
Finally, delete the unused n8n credential through the n8n interface. Never
delete or recreate the n8n container as part of this uninstall.
## Future official n8n support
As of July 28, 2026, an
[open n8n pull request](https://github.com/n8n-io/n8n/pull/29184) proposes
native OpenAI Account authentication for the OpenAI Chat Model. It is not yet
merged. If n8n later ships and documents an official equivalent, prefer the
official built-in route and retire this sidecar after testing migration.