Railway upgrade and recovery

Railway recovery is one phase of a single protected upgrade transaction. The CLI does not provide an independent host backup, host restore, or command that drops an arbitrary old Server into a fresh Railway project on its own.

When an authorized operator runs host upgrade, OpenCircle quiesces the Server, creates a coordinated set of Railway-native volume backups, exports an encrypted portable copy to operator-controlled storage, applies and verifies the selected release, and records durable checkpoints. If the in-place candidate cannot be accepted, the same transaction can restore the portable copy into a replacement project and promote it.

Required authority

• the saved OpenCircle launch receipt on the administrator workstation;
• Railway access to the paying workspace and exact project;
• a private S3-compatible bucket outside the Railway project;
• credentials scoped to only the chosen recovery prefix; and
• one independently stored 32-byte encryption key.

Create the protected recovery file

install -d -m 700 "$HOME/.config/opencircle"
umask 077
${EDITOR-vi} "$HOME/.config/opencircle/railway-recovery.toml"
chmod 600 "$HOME/.config/opencircle/railway-recovery.toml"

schemaVersion = 1
[storage]
endpoint = "https://s3.example.com"
region = "us-east-1"
bucket = "<private-recovery-bucket>"
objectPrefix = "opencircle-recovery"
accessKeyId = { fromEnv = "OPENCIRCLE_RECOVERY_ACCESS_KEY_ID" }
secretAccessKey = { fromEnv = "OPENCIRCLE_RECOVERY_SECRET_ACCESS_KEY" }
encryptionKey = { fromEnv = "OPENCIRCLE_RECOVERY_ENCRYPTION_KEY" }

Generate the encryption value as exactly 32 random bytes in a private terminal with history disabled, then store it directly in a password manager:

openssl rand 32 | openssl base64 -A | tr '+/' '-_' | tr -d '='

The CLI refuses a relative path, a symlink, a file it does not own, unsafe permissions, unexpected keys, missing environment variables, or a malformed key — repair the input rather than weakening its permissions.

Inspect the exact launch

export OPENCIRCLE_LAUNCH_ID='<saved-launch-id>'
export OPENCIRCLE_RECOVERY_CONFIG="$HOME/.config/opencircle/railway-recovery.toml"
opencircle host inspect --backend railway --launch "$OPENCIRCLE_LAUNCH_ID" --json

Require the intended workspace, project, public domains, release, and a healthy saved launch. Stop on ambiguity or a project someone else is actively changing.

Review, confirm, and stay attached

Run the upgrade once without --yes to review the target, then confirm the same operation and keep the process attached while checkpoints advance — the Server is unavailable during maintenance.

opencircle host upgrade \
  --backend railway \
  --launch "$OPENCIRCLE_LAUNCH_ID" \
  --recovery-config "$OPENCIRCLE_RECOVERY_CONFIG" \
  --yes --json

If the terminal closes or connectivity drops, resume with the same launch, recovery file, and encryption key rather than starting a second upgrade.

What recovery does and does not mean

• The encrypted portable copy is written during the upgrade itself; there is no separate command to create it on demand.
• A replacement project is created only when the active transaction needs its fallback path — it is not a general restore target.
• A promoted replacement becomes the active saved launch; the source project is retained rather than silently deleted.
• Manually restoring a Railway volume outside this transaction can break later custody checks — it is not a routine continuation for an interrupted upgrade.

After completion, run host inspect for the active launch, sign in as the existing owner, and complete one useful model-backed reply before considering the maintenance done.