feat(security): support optional encrypted-at-rest secrets via SOPS (re #233)

[nickorlabs]

Summary

Adds opt-in SOPS support so deployers who want it can encrypt true secrets (OPENAI_API_KEY, ODYSSEUS_ADMIN_PASSWORD, ODYSSEUS_INTERNAL_TOKEN, MCP OAuth secrets, IMAP passwords, etc.) at rest instead of leaving them plaintext in .env. The feature is only active when an encrypted secrets.env is mounted at container start; existing deployments behave bit-for-bit identically.

Linked Issue

Fixes #233

Scope (narrowed per reviewer feedback)

• In scope: Docker entrypoint SOPS hook for app-internal secrets read by the wrapped odysseus process. setup.py runs inside the wrap so the encrypted ODYSSEUS_ADMIN_PASSWORD reaches the admin seed.
• Out of scope, deferred to follow-ups:
  • Cross-service compose secrets (SEARXNG_SECRET etc., which need host-side compose interpolation) — see the linked tracking issue.
  • Build-context / .gitignore / .dockerignore hardening for plaintext-and-decrypt artifacts — shipping as a small standalone PR so it can land independently.
  • Native (uvicorn app:app, systemd, launchd) startup hooks — SECURITY.md states the scope; native users wrap their own launch.

Type of Change

• Bug fix (non-breaking — fixes a confirmed issue)
• New feature (non-breaking — adds new behaviour)
• Breaking change (changes or removes existing behaviour)
• Refactor / cleanup (behaviour unchanged)
• Documentation only
• CI / tooling / configuration

Checklist

• I searched open issues and open PRs — this is not a duplicate.
• This PR targets dev
• My changes are limited to the scope described above — no unrelated refactors or whitespace changes mixed in.
• I actually ran the app (docker compose up) and verified the change works end-to-end. Type-checks and unit tests are not enough.

How to Test

End-to-end verified on an Ubuntu 24.04 / Docker 29.4.3 host; reproducible in <5 minutes.

1. Generate an age key on the host:

   mkdir -p ~/.config/sops/age
   age-keygen -o ~/.config/sops/age/keys.txt && chmod 600 ~/.config/sops/age/keys.txt
   age-keygen -y < ~/.config/sops/age/keys.txt    # prints the public key

2. Edit .sops.yaml in the repo root: replace the age1REPLACE... placeholder with the public key from step 1.
3. Create + encrypt your secrets:

   cp secrets.env.example secrets.env
   $EDITOR secrets.env                       # add ODYSSEUS_TEST_SECRET=hello-from-sops (or real values)
   sops -e -i secrets.env                    # encrypt in place

4. Mount the encrypted file and the age key into the container via docker-compose.override.yml:

   services:
     odysseus:
       volumes:
         - ./secrets.env:/app/secrets.env:ro
         - ~/.config/sops/age/keys.txt:/run/secrets/sops-age-key:ro
       environment:
         - SOPS_AGE_KEY_FILE=/run/secrets/sops-age-key

5. Boot: docker compose up -d --build
6. Verify:
   • docker exec odysseus-odysseus-1 ps -ef | head -3 — PID 1 should be sops exec-env /app/secrets.env ...
   • docker exec -u 1000 odysseus-odysseus-1 sh -c "tr '\0' '\n' < /proc/<uvicorn-pid>/environ" | grep ODYSSEUS_TEST_SECRET — should print the plaintext value
   • First-boot admin seed: container logs Initial admin user created (admin) with no random-password notice — confirms ODYSSEUS_ADMIN_PASSWORD reached setup.py inside the SOPS wrap
   • docker exec odysseus-odysseus-1 head -2 /app/secrets.env — shows ENC[AES256_GCM,...] markers, never plaintext
   • docker exec odysseus-odysseus-1 grep -rI hello-from-sops /app /tmp 2>/dev/null — empty (plaintext never written to disk)
   • HTTP serves: docker exec odysseus-odysseus-1 curl -s -o /dev/null -w "%{http_code}\n" http://localhost:7000/ → 302
7. Negative path: remove the secrets.env mount, docker compose up -d. Container boots identically to current dev; entrypoint takes the existing exec gosu path with no SOPS-related logic touched.
8. Refuse-to-start path: mount a plaintext (non-SOPS) secrets.env at /app/secrets.env. Container exits 1 with a helpful error pointing at sops -e -i secrets.env — prevents the silent-shipping-plaintext-secrets footgun.

Addressing the four surfaces called out on #233

The maintainer noted on #233: "secret storage touches setup, backups, Docker/native installs, and migration behavior." Each:

Setup: setup.py runs inside the sops exec-env wrap when an encrypted secrets.env is present, so the encrypted ODYSSEUS_ADMIN_PASSWORD reaches the admin-seed step. In the non-SOPS path setup.py runs as today. The script remains idempotent and runs as the dropped user via gosu.

Backups: This is the design point that makes SOPS attractive vs Fernet. The encrypted secrets.env file is safe to commit and back up alongside the repo; the age private key (~/.config/sops/age/keys.txt, 0600) is the ONLY thing that must be backed up separately. SECURITY.md says this explicitly. There's no parallel "back up data/.app_key" footgun the way Fernet-based DB encryption has, because the encrypted file is content-addressable and recoverable from any backup including git.

Docker vs native installs: This PR is Docker-only — only docker/entrypoint.sh invokes sops exec-env. Native (uvicorn app:app) installs are unaffected; native users wrap their own launch with sops exec-env. SECURITY.md documents this explicitly. A first-class native hook is out of scope here and can be a separate PR if requested.

Migration: One-step, no breakage. Existing users keep their plaintext .env unchanged. To move to encrypted: move the secret-flavored lines out of .env into secrets.env, run sops -e -i secrets.env, restart with the mount in place. The PR's secrets.env.example lists exactly which keys are expected as secrets and notes which ones are out of scope (e.g. SEARXNG_SECRET).

Naming hazard

The codebase already has routes/vault_routes.py (Bitwarden/Vaultwarden integration — a runtime feature). To avoid collision this PR uses "encrypted secrets at rest" / "SOPS" / secrets.env throughout — never "vault."

Diff

 .sops.yaml           |  13 +++++++++++++
 Dockerfile           |  21 +++++++++++++++++++--
 SECURITY.md          |  56 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 docker/entrypoint.sh |  47 ++++++++++++++++++++++++++++++++++++++++---
 secrets.env.example  |  36 +++++++++++++++++++++++++++++++++
 5 files changed, 170 insertions(+), 3 deletions(-)

No application code touched. Image grows ~10MB (one static Go binary for sops).

Visual / UI changes

No UI changes. All edits are infrastructure (Dockerfile, entrypoint, docs).

[nickorlabs]

End-to-end validation on a Linux/Docker server

Stood the full stack up on an Ubuntu 24.04 / Docker 29.4.3 host using this branch — closing the maintainer-checkbox in the test plan.

Setup performed (matches the SECURITY.md workflow exactly)

git clone <fork> && git checkout feat/sops-encrypted-secrets
age-keygen -o ~/.config/sops/age/keys.txt && chmod 600 ~/.config/sops/age/keys.txt
# Paste the public key into .sops.yaml
cp secrets.env.example secrets.env
$EDITOR secrets.env              # added ODYSSEUS_TEST_SECRET=hello-from-sops-2026
sops -e -i secrets.env           # encrypt in place
docker compose up -d --build

docker-compose.override.yml was used to bind-mount the age private key (/run/secrets/sops-age-key) and set SOPS_AGE_KEY_FILE — same shape as the README example.

Six gates, all green

1. PID 1 inside the container is sops exec-env wrapping uvicorn

UID         PID  PPID  CMD
odysseus      1     0  sops exec-env /app/secrets.env exec 'uvicorn' 'app:app' '--host' '0.0.0.0' '--port' '7000'
odysseus     84     1  /usr/local/bin/python3.12 /usr/local/bin/uvicorn app:app --host 0.0.0.0 --port 7000

2. Sentinel secret IS in uvicorn's process environment (read via /proc/<pid>/environ as the owning uid)

ODYSSEUS_TEST_SECRET=hello-from-sops-2026
PGID=1000
PUID=1000

3. secrets.env on disk is encrypted (file mounted from the image)

#ENC[AES256_GCM,data:myZekD5n4QtX...,iv:LvPGVuqQ7Svw...,tag:UiQWcgFX8l2pX8FE2cS61g==,type:comment]
ODYSSEUS_TEST_SECRET=ENC[AES256_GCM,data:yl/5B+J5o3kU...,iv:VbW99X/r/j1yA0gqv6dU4rqx...]

4. Plaintext value of the sentinel appears NOWHERE on the container filesystem

$ docker exec odysseus-odysseus-1 grep -rI hello-from-sops-2026 /app /tmp 2>/dev/null
(empty — no leak)

5. Secrets are scope-isolated to uvicorn's child tree — a fresh docker exec env does NOT see them

$ docker exec odysseus-odysseus-1 env | grep ODYSSEUS_TEST_SECRET
(empty — pass)

This is a nice bonus property: an attacker who lands a container exec shell after boot can't lift the SOPS-injected env from env//proc/self/environ. They'd need to read /proc/<uvicorn-pid>/environ as uid 1000.

6. The app boots and serves normally

$ docker exec odysseus-odysseus-1 curl -s -o /dev/null -w 'HTTP %{http_code}\n' http://localhost:7000/
HTTP 302
# Logs show clean ChromaDB connect, 58 tools indexed, 5 built-in MCP servers up, NPX Browser MCP started, /docs reachable.

Compatibility note — re: #511 (Secure by default uplift, merged today)

Checked: zero file overlap between this PR and #511. The PR currently reports mergeStateStatus: CLEAN, mergeable: MERGEABLE. The two changes encrypt different layers:

• Secure by default uplift #511 — runtime user-added integration credentials in data/integrations.json (Fernet, app-managed key)
• feat(security): support optional encrypted-at-rest secrets via SOPS (re #233) #236 (this PR) — deployment-time env-loaded secrets like OPENAI_API_KEY / ODYSSEUS_ADMIN_PASSWORD / SEARXNG_SECRET (SOPS, user-managed age key)

They cover complementary surfaces.

Ready for review whenever convenient. Happy to rebase or adjust scope (e.g. gate sops install behind a build ARG so non-users don't pull the ~10MB binary, or swap age for GPG/cloud KMS) on request.

[nickorlabs]

Rebased on current main (post-#511) + re-validated

Pulled #511 (and the other 13 commits since this branch forked) and rebased. Diff stat unchanged: still 6 files, +141/-0.

 .gitignore           |  8 ++++++++
 .sops.yaml           | 13 +++++++++++++
 Dockerfile           |  9 +++++++++
 SECURITY.md          | 51 +++++++++++++++++++++++++++++++++++++++++++++++++++
 docker/entrypoint.sh | 33 +++++++++++++++++++++++++++++++++
 secrets.env.example  | 27 +++++++++++++++++++++++++++

Three trivial 3-way merges happened on rebase (in your favor):

• docker/entrypoint.sh — your new VLLM_USE_FLASHINFER_SAMPLER + extra CUDA wheel path block landed above my SOPS block cleanly
• .gitignore — your docs/windows-port/ addition + mine
• Dockerfile — your services/cache/search mkdir + mine

No semantic conflicts. PR status: mergeStateStatus: CLEAN, mergeable: MERGEABLE.

Re-validated on the same Ubuntu/Docker host, all 6 gates green

Gate 1  PID 1 is `sops exec-env` wrapping uvicorn  ✓
Gate 2  Sentinel in /proc/<uvicorn>/environ        ✓  ODYSSEUS_TEST_SECRET=hello-from-sops-2026
Gate 3  /app/secrets.env on disk is encrypted      ✓  ENC[AES256_GCM,...] markers
Gate 4  No plaintext value anywhere on disk        ✓  grep -rI on /app /tmp returns nothing
Gate 5  Fresh `docker exec env` sees no secrets    ✓  scope-isolated to uvicorn child tree
Gate 6  HTTP 302 from / (login redirect)           ✓  including across Tailscale

Compatibility with #511's new APP_BIND

Set APP_BIND=0.0.0.0 in the deployer's .env to keep the container reachable on the LAN/tailnet. Default loopback bind from #511 is preserved — SOPS doesn't interact with it.

Ready for review.

[nickorlabs]

Rebased on current main

Upstream moved while this PR was waiting; conflicts surfaced and I just rebased.

• New base: c075abc Search: consolidate core and provider implementations
• One auto-merge needed: docker/entrypoint.sh — your PR Expose Cookbook user-install CLIs in Docker #887 added an export PATH="/app/.local/bin:$PATH" line right after the VLLM_USE_FLASHINFER_SAMPLER block, and this PR's SOPS block targets the same spot. Resolution: keep both, in the order PATH first, then SOPS block (PATH always runs; SOPS only fires if secrets.env is present).
• .gitignore and SECURITY.md auto-merged.

Diff stat unchanged: still 6 files, +141/-0, same shape, same semantics.

Status: MERGEABLE / CLEAN. Ready when convenient.

[alteixeira20]

Thanks for the detailed write-up and validation.

I did a focused local audit. From the local checks, I did not find a concrete merge blocker:

• scope is coherent and limited to SOPS/encrypted-at-rest secrets support;

• no application runtime code is touched;

• git diff --check passed;

• focused security-related tests passed:

  • tests/test_api_chat_security.py
  • tests/test_backup_cli_security.py
  • tests/test_email_smtp_security.py
  • tests/test_security_regressions.py
  • result: 112 passed;

• merge probe into current upstream/dev was clean.

That said, I do not think I should approve or merge this without maintainer/security direction from @pewdiepie-archdaemon. This changes deployment and secret-management policy, including Docker image contents, entrypoint behavior, backup/key-management expectations, and the intended workflow around committable encrypted secrets.env files.

A few points I would want maintainer confirmation on before merge:

• whether SOPS should be installed into every Docker image by default, or gated behind a build arg/optional image path;
• whether downloading the SOPS binary in the Dockerfile needs checksum/signature verification;
• whether the tracked .sops.yaml placeholder workflow is the desired UX, or whether .sops.yaml.local / documented local config is safer;
• whether “encrypted secrets.env is committable” is acceptable project guidance for this repo’s expected users;
• whether Docker-only support is the intended first slice, with native/systemd/launchd wrappers left for follow-up.

Technically promising, but I’d leave final approval/merge to @pewdiepie-archdaemon because this is security/deployment policy, not just implementation correctness.

Best regards,
Alexandre.

[nickorlabs]

Quick workflow question now that dev is live alongside main: should this PR retarget to dev?

My read is main is still the right base — SOPS is infra-only (Dockerfile, entrypoint, gitignore, SECURITY.md), no feature code that needs dev's bake time, and the diff doesn't conflict with anything in dev. But if dev is now the default base for all incoming PRs regardless of category, happy to rebase onto it. Either way is one rebase.

[alteixeira20]

Thanks for asking.

Yes, I think this should target dev now.

The PR metadata already shows dev, but the current diff still includes unrelated main-side files (routes/document_routes.py, routes/gallery_routes.py, routes/task_routes.py, and src/caldav_sync.py), and GitHub reports it as DIRTY / CONFLICTING.

Could you please rebuild/rebase from current dev so the diff is SOPS-only again?

Expected final scope:

• .gitignore
• .sops.yaml
• Dockerfile
• SECURITY.md
• docker/entrypoint.sh
• secrets.env.example

Also please update the PR body checklist from main to dev.

Once that is clean, I can re-review the actual SOPS/security-policy questions separately.

[nickorlabs]

Retargeted to dev. Rebased with --onto to keep only the SOPS commit (so the 4 main-only auth/security backports don't get replayed on top of dev). Two-dot diff is still the same 6 files, +141/-0.

$ git diff --name-only origin/dev..HEAD
.gitignore
.sops.yaml
Dockerfile
SECURITY.md
docker/entrypoint.sh
secrets.env.example

$ git diff --stat origin/dev..HEAD
 6 files changed, 141 insertions(+)

Branch HEAD: 5d2a78e. Ready for review against dev.

[alteixeira20]

Thanks, the rebase/scope issue is resolved now. The branch is clean against dev, checks are green, and the diff is back to the expected six SOPS-only files.

I still have one blocker before merge: the Dockerfile downloads the SOPS release binary with curl and makes it executable, but does not verify a checksum or signature.

Since this PR adds a secrets/deployment path, I think the install path should verify the downloaded binary in the same PR. Once that is added, this should be straightforward to approve.

[RaresKeY]

In addition to the already-raised checksum/signature blocker for the downloaded SOPS binary, I found two deployment-contract issues in the encrypted env workflow.

Findings

issue (security): Keep plaintext secret files out of the Docker build context

• Problem: The new runtime check refuses a plaintext /app/secrets.env, but the Dockerfile has already copied the full build context into the image by then. .dockerignore excludes .env but not secrets.env or the new plaintext transient names, so a forgotten plaintext file or decrypt artifact can be baked into image layers before the entrypoint exits.

• Impact: This defeats the new plaintext-at-rest guarantee and can leak real deployment secrets through local image cache or any pushed image.

• Ask: Keep secrets.env* out of the image build context and provide the encrypted file at runtime instead, or add an equivalent design that prevents plaintext files from entering Docker layers before validation runs.

• Location: Dockerfile:42

issue (security/deployment): The SOPS wrapper does not reach every secret consumer listed in the docs

• Problem: The docs/example list ODYSSEUS_ADMIN_PASSWORD and SEARXNG_SECRET as values to move into encrypted secrets.env, but setup reads the admin password before sops exec-env, and SearXNG is a separate service outside the wrapped Odysseus process.

• Impact: Users can follow the migration guide and still not have those secrets applied through the encrypted path.

• Ask: Either wire those consumers into the SOPS-supported path, or narrow the docs/example to variables actually consumed by the wrapped Odysseus process.

• Location: docker/entrypoint.sh:86

Validation

Ran git diff --check, sh -n docker/entrypoint.sh, and focused setup/security tests. Docker build/compose E2E was not run.

[nickorlabs]

Thanks will look at this later today and make updates.

[alteixeira20]

Thanks for the re-scope. Most of the previous security/deployment concerns look resolved now: checksum verification is present, the mixed Compose workflow is removed, Docker-only scope is explicit, SEARXNG_SECRET is out of scope, and the internal token name is now ODYSSEUS_INTERNAL_TOKEN.

I found one remaining small blocker before approval: .sops.yaml still says users can copy the config to .sops.yaml.local, but the documented encryption command is plain sops -e -i secrets.env. SOPS will discover .sops.yaml by default, not .sops.yaml.local, unless users pass an explicit config path. This reintroduces the config-discovery confusion from the earlier review.

Could you remove the .sops.yaml.local suggestion and keep the guidance aligned with editing .sops.yaml in place?

[RaresKeY]

Current-head follow-up review. This is not replacing or restating the earlier feedback: the earlier .sops.yaml.local config-discovery blocker looks fixed on this head, so I’m only adding the non-duplicative issues I found on the current head.

Findings

issue (runtime): Keep the app as the Docker stop signal target in SOPS mode

• Problem: The non-SOPS path ends by execing the app through gosu, so Docker stop signals reach the application process directly. The SOPS path instead execs gosu ... sops exec-env ..., and SOPS then starts the final command in its default child-process mode. The shell's final exec$cmd replaces only SOPS' shell child, not the SOPS process that Docker targets as PID 1.

• Impact: SOPS-enabled containers can skip the normal graceful shutdown path. In a SOPS 3.13.1 probe with the current command shape, plain exec-env left the final child running after SIGTERM, while the same command with --same-process made the child own the SOPS PID and receive SIGTERM.

• Ask: Preserve the no-SOPS signal contract in the SOPS branch, for example by using sops exec-env --same-process "$SECRETS_FILE" "python /app/setup.py || true; exec$cmd" or an equivalent structure where the final app process is the signal target.

• Location: docker/entrypoint.sh:119

issue (docs): Quote the native exec-env command as one shell command string

• Problem: SECURITY.md tells native users to wrap startup with sops exec-env secrets.env -- uvicorn app:app ..., but SOPS v3.13.1 exec-env takes exactly two positional arguments and runs the second as a shell command string. It is not argv passthrough.

• Impact: Native users following the documented workaround fail before Odysseus starts, which undermines the Docker-only scope guidance added by this PR.

• Ask: Change the example to a single quoted command string, such as sops exec-env secrets.env 'uvicorn app:app ...', or otherwise document the exact SOPS-supported syntax.

• Location: SECURITY.md:30

Validation

Ran:

• git diff --check origin/dev...HEAD
• sh -n docker/entrypoint.sh
• docker compose --env-file /dev/null config
• verified SOPS v3.13.1 exec-env parser behavior
• reproduced the SOPS exec-env signal behavior with a throwaway encrypted dotenv

Not run:

• Full Docker build.
• Live container boot with mounted encrypted secrets.env and age key.
• Full local pytest.

[nickorlabs]

@alteixeira20 — good catch, thanks. That was a genuine miss on my end: .sops.yaml had skip-worktree set on my dev host (keeping local recipient keys out of git), so the rewrite of that file silently never reached the index when I amended for the narrowing. Apologies for the noise.

Pushed 7ff17f8 with the actual fix — the comment block now reads:

# SOPS encryption configuration for Odysseus secrets at rest.
#
# Replace the placeholder below with your own age public key, then
# encrypt with: sops -e -i secrets.env

No more .sops.yaml.local reference; the discovery path matches the documented sops -e -i secrets.env command. Verified via raw URL after the push so we don't re-litigate the same hidden-file mistake.

[alteixeira20]

Thanks, the .sops.yaml.local issue is fixed.

I still would not approve this yet because two current-head issues remain:

1. In docker/entrypoint.sh, please preserve the normal Docker stop-signal/shutdown contract in SOPS mode. The current sops exec-env path still leaves SOPS as the process supervising the app command instead of replacing itself with the final app process. Please use sops exec-env --same-process or an equivalent structure so the final Odysseus process receives Docker stop signals the same way it does in the non-SOPS path.

2. In SECURITY.md, please update the native wrapper example. sops exec-env expects the secrets file plus one command string, not argv-style passthrough. The documented example should quote the command, for example:

   sops exec-env secrets.env 'uvicorn app:app --host 0.0.0.0 --port 7000'

Once those are fixed, I can re-review the narrowed SOPS-only diff.

[nickorlabs]

Thanks @RaresKeY. Both findings fixed on 48cae76.

N6 (P1 — SIGTERM not reaching the app in SOPS mode)

Added --same-process to the sops exec-env invocation:

exec gosu "$PUID:$PGID" sops exec-env --same-process "$SECRETS_FILE" \
    "python /app/setup.py || true; exec$cmd"

Verified end-to-end in a throwaway container with a real encrypted secrets.env + age key mount:

• PID 1 ownership: ps -ef inside the container shows the chain's final sh -c (running as odysseus, UID 1000) as PID 1 — sops is no longer in the process tree.
• Graceful shutdown: docker stop --timeout 10 against a CMD that traps SIGTERM and exits 0 completed in 0.59s, with the trap firing on PID 1:

  READY_AT_PID_$$
  GOT_SIGTERM_AT_PID_1
  

  Matches the no-SOPS branch's signal contract.
• SOPS injection still works: same container with a CMD that dumps env: TEST_SECRET=... and ADMIN_PW=... both injected from the encrypted file, and setup.py logged Initial admin user created (admin) (the seeded password, not a random one) — proving the encrypted ODYSSEUS_ADMIN_PASSWORD still reaches setup.py under --same-process.

N7 (P3 — wrong native exec-env syntax in docs)

The Scope paragraph in SECURITY.md was using sops exec-env secrets.env -- uvicorn app:app ... (argv-passthrough), which v3.13.1 exec-env doesn't accept. Replaced with the single shell-string form, and noted the --same-process flag for the same signal-reaching reason:

sops exec-env --same-process secrets.env 'uvicorn app:app --host 0.0.0.0 --port 7000'

Diff (5 files, +177/-3)

 .sops.yaml           |  13 +++++++++++++
 Dockerfile           |  21 +++++++++++++++++++--
 SECURITY.md          |  56 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 docker/entrypoint.sh |  54 +++++++++++++++++++++++++++++++++++++++++++++++++---
 secrets.env.example  |  36 +++++++++++++++++++++++++++++++++

[nickorlabs]

@alteixeira20 — the two concerns in your latest review are exactly the same as @RaresKeY's N6 + N7, which I'd already fixed in the prior head 48cae76 (your review timestamp was ~2h before that push landed, so you were reading 7ff17f80).

Rebased onto current dev and resolved the conflict with #4349 — head is now 8b5d229. The SOPS branch now uses the $GOSU_BIN / $PYTHON_BIN variables introduced by #4349 instead of calling gosu / python directly, so the entrypoint is internally consistent:

exec "$GOSU_BIN" "$PUID:$PGID" sops exec-env --same-process "$SECRETS_FILE" \
    "$PYTHON_BIN /app/setup.py || true; exec$cmd"

Re-ran the same end-to-end signal + decryption test against the rebased image:

--- PID 1 ---
odysseus  1  0 ... sh -c trap "echo TRAPPED..." TERM; echo READY...; sleep 60 & wait
--- docker stop --timeout 10 ---
real    0m1.206s
--- logs ---
[ok] Initial admin user created (admin)
READY_PID_$$_SECRET=$ODYSSEUS_TEST_SECRET
TRAPPED_PID_1_SECRET=postrebase-2026-06-16

So: PID 1 = the final shell (running as odysseus / UID 1000, not as sops), docker stop exits in ~1.2s, the SIGTERM trap fires on PID 1 with the decrypted secret in the env, and setup.py still sees the encrypted ODYSSEUS_ADMIN_PASSWORD (no random password). All four invariants match the no-SOPS contract.

SECURITY.md's native example is the single quoted shell-string form you cited:

sops exec-env --same-process secrets.env 'uvicorn app:app --host 0.0.0.0 --port 7000'

Diff stat unchanged at 5 files / +177 / -3. Ready for re-review when you have time.

[nickorlabs]

@alteixeira20 @RaresKeY — when you have a moment, could you take another look? Both of your "Request Changes" reviews above are against commit 7ff17f80; the current head is 8b5d229 and contains the fixes you each asked for. A quick recap so you don't have to scroll the thread:

• --same-process for SIGTERM forwarding — docker/entrypoint.sh:159 now reads exec "$GOSU_BIN" "$PUID:$PGID" sops exec-env --same-process "$SECRETS_FILE" "$PYTHON_BIN /app/setup.py || true; exec$cmd". Validated end-to-end on a real encrypted container: PID 1 = the final shell (UID 1000, not sops), docker stop --timeout 10 exits in 1.21s with the SIGTERM trap firing on PID 1, and setup.py still gets the encrypted ODYSSEUS_ADMIN_PASSWORD (logs Initial admin user created (admin), not random).
• Native exec-env shell-string syntax — SECURITY.md:30 now reads sops exec-env --same-process secrets.env 'uvicorn app:app --host 0.0.0.0 --port 7000' (single quoted command string, not -- argv passthrough).
• Rebase onto current dev — picked up $GOSU_BIN / $PYTHON_BIN from fix(devops): harden docker config defaults #4349 and threaded them through the SOPS branch, so the entrypoint is internally consistent. Diff stat 5 files / +177 / -3.

No further code changes pending — happy to address anything new the latest head surfaces, but the two items you flagged should both be resolved now.

[alteixeira20]

Sorry for the delay, tomorrow I'll take a couple of hours to get up to speed, I'm not home at the moment

[nickorlabs]

@alteixeira20 @RaresKeY — when you have a moment, could you take another look? The current head 8b5d229 has the two items you each flagged resolved:

• --same-process is now passed to sops exec-env so SIGTERM reaches PID 1 and docker stop behaves like the non-SOPS path.
• The native exec-env example in SECURITY.md uses the correct single quoted shell-string form.
• Rebased onto current dev and picked up the $GOSU_BIN / $PYTHON_BIN variables from fix(devops): harden docker config defaults #4349.

No further changes are pending from my side — happy to address anything new the latest head surfaces. Thanks!

[RaresKeY]

Thanks for the updates. Before I re-review this, could you please refresh/rebase the branch against current dev? GitHub currently reports the PR as DIRTY / CONFLICTING (mergeable: false, rebaseable: false) on head 8b5d229, so I can’t verify the latest SOPS diff cleanly against the current base yet.

The visible scope still looks SOPS-only (.sops.yaml, Dockerfile, SECURITY.md, docker/entrypoint.sh, secrets.env.example). After the rebase/conflict fix, please confirm the diff is still limited to that scope and rerun the relevant Docker/SOPS validation. Then I can re-review the updated head.