BYO Gemini: How HelaSyn Cloud Handles Your API Credential

What Is BYO-Gemini?

BYO-Gemini (Bring Your Own Gemini) is an opt-in feature for HelaSyn Cloud that lets you connect your own Google AI Studio or Google Vertex AI API credential to any of your bots. When active, your bot's inference runs on Google Gemini models using your account — not HelaSyn's default Anthropic credit pool.

By default, every HelaSyn Cloud bot runs on Claude via HelaSyn's Anthropic-paid credits ($1/day included on the free plan). BYO-Gemini routes a bot to Google Gemini instead, defaulting to gemini-2.5-flash (the model an unpaid AI Studio key can drive — Gemini API pricing), with a per-call model override for users on paid Google AI or Vertex AI accounts. The feature is opt-in and configured per bot.

The design has one non-negotiable requirement: HelaSyn Cloud's web tier must never decrypt your API credential. The web tier can wrap (encrypt) it but never unwrap it; decryption and use happen in separate, more privileged processes. (Internal design: design/gemini-byo-key.md.)

The Design Principles

Most multi-tenant SaaS products that accept third-party API credentials store them in their own database and inject them via environment variables at runtime. That approach is convenient. It is also a single point of failure: one database breach or misconfigured env dump exposes every user credential in the system.

HelaSyn takes a different approach. ADR-016 (the BYO-Gemini architecture design) is built around three design principles:

Your credential never enters an environment variable
Your plaintext credential never reaches HelaSyn Cloud's web tier — only the engine that uses it and one privileged supervisor process that decrypts it ever hold it in the clear
Validation fails closed — no confirmation means no access

These are design commitments for a feature that has not shipped yet. One of them — the scope of the decrypt step in principle 2 — is still an open item (tracked internally as GAP-5). We describe it honestly below rather than claim it is solved.

Principle 1: Credential Never Enters an Environment Variable

When your bot activates BYO-Gemini, a privileged supervisor process decrypts your stored credential and writes the plaintext into a pipe file descriptor (pipe FD) — a Unix inter-process channel inherited by the bot engine. The engine worker reads it from the pipe after fork. The credential moves as an in-memory payload inside the FD handshake and is never written to disk in transit.

It never appears in:

Environment variables (os.environ)
Command-line arguments (sys.argv)
Log files
Disk storage during transit

The only thing that enters the environment is a non-sensitive selector: HELASYN_LLM_BACKEND=gemini. That tells the engine which LLM provider to activate. Your actual credential stays in memory inside the engine process, loaded from the pipe FD payload — not from the environment.

This design reuses the ADR-007 pipe-FD transport rather than inventing a new one, but it does add a dedicated file descriptor (FD 4) for the Gemini key, alongside ADR-007's existing FD 3 channel-token contract, which stays locked and unchanged. The transport mechanism — an inherited pipe FD — is reused; the new piece is a second secret riding its own FD on the same handover. (Internal design: design/gemini-byo-key.md.)

Principle 2: Plaintext Stays Off the Web Tier

HelaSyn has two distinct layers: HelaSyn (the engine that runs your bot) and HelaSyn Cloud (the web platform, subscription management, and routing layer). The web tier cannot import HelaSyn engine modules, and — this is the security-relevant part — it cannot decrypt your credential at all. Its IAM role holds only kms:Encrypt, so it can wrap your key but never unwrap it (ADR-009).

When you enable BYO-Gemini via the Cloud dashboard, the web tier stores an encrypted credential blob (protected at rest using the same credential-class storage mechanism used for all HelaSyn user credentials, ADR-009). The decrypt does not happen in the web tier. It happens in a separate, more privileged supervisor process, which uses its privileged decrypt capability to decrypt the blob and then hands the plaintext to the engine over the pipe FD at bot startup. Inside the engine, the credential lives in helasyn/llm/gemini.py, which implements the LLMProvider protocol.

So plaintext is touched by exactly two processes: the supervisor that decrypts it and the engine that uses it. The web platform code never sees it in the clear.

The honest caveat (GAP-5). That supervisor decrypt is the open item. Tightening it — scoping the decrypt permission per account via STS-assumed roles, rather than leaving a broad decrypt capability in the supervisor — is tracked internally as GAP-5 and is not fully closed in this design (per-account encryption keys are deferred to a later release). We are deliberately not claiming the credential "lives only in the engine" or is "invisible," because for a transient window the supervisor process holds it in plaintext. We call that out so the boundary is judged on what it actually is. (Internal design: design/gemini-byo-key.md; ADR-009 GAP-5.)

Principle 3: Validation Fails Closed

Before your bot begins inference with BYO-Gemini, the design requires validating that your credential works — confirming reachability of the Google AI endpoint and that the credential is neither expired nor quota-exhausted.

The planned mechanism (ADR-016) reuses HelaSyn's existing worker_intents Postgres broker channel rather than adding new infrastructure. Today that broker carries operational actions (spawn, stop, restart); the design adds a new validation action on the same channel. The supervisor — the only process that can decrypt — runs a transient one-token Gemini ping inside the engine boundary and writes a durable result row keyed by a unique request_id, carrying only a status (never the key, never any Gemini response body). The web tier polls for that result. This part is designed, not yet built.

The default is fail-closed. If no result row arrives within the bounded wait (roughly 10 seconds) — for any reason (network fault, supervisor crash, invalid credential, or unexpected delay) — BYO-Gemini is not activated, the save is rejected, and nothing is persisted. The bot stays on the default Claude lane.

There is no optimistic default-allow path. Silence means denial.

What Opt-In Per Bot Means in Practice

BYO-Gemini is configured individually per bot, not at the account level:

You can run some bots on Gemini and others on Claude within the same account
Activating BYO-Gemini on one bot does not affect any other bot
Each bot's credential association is independently revocable

When you enable BYO-Gemini, HelaSyn presents a consent screen confirming that data processed by that bot will be subject to Google's Gemini API terms and Google's data handling policies — not Anthropic's. Acknowledgment is required before the feature activates.

HelaSyn's default free plan ($1/day Anthropic-paid credits) remains unchanged for all bots not using BYO-Gemini.

Q&A

What is BYO-Gemini? BYO-Gemini is a HelaSyn Cloud feature that lets you run your bots on Google Gemini models using your own Google AI Studio or Google Vertex AI API credential, instead of HelaSyn's default Anthropic credit pool.

Does HelaSyn store my API credential? Yes, encrypted at rest using HelaSyn's credential-class storage (ADR-009). HelaSyn Cloud's web tier can wrap (encrypt) it but cannot decrypt it — that IAM role holds only kms:Encrypt. Decryption happens in a separate, more privileged supervisor process, which hands the plaintext to the engine over the pipe FD at bot startup. The web platform code never sees the credential in the clear. Tightening the scope of that supervisor decrypt is an open design item (GAP-5).

What happens if my credential is invalid or expires? Validation fails closed. Your bot will not run on BYO-Gemini until a valid confirmation is received. It falls back to the default Claude lane with no conversation data lost.

Which Gemini models are supported? The v1.1 design targets Google AI Studio (default) and Google Vertex AI. Gemini CLI and OAuth-based credential flows are explicitly out of scope — they conflict with Google's terms for automated use.

Does activating BYO-Gemini affect my other bots? No. BYO-Gemini is opt-in per bot. All other bots in your account are unaffected.

When will BYO-Gemini be available? BYO-Gemini is currently in design review and gate clearance. We will announce availability once the security and quality gates clear and the feature reaches the v1.1 milestone.

What Is Next

BYO-Gemini has completed architecture review (ADR-016 with DEVON-044 E1+E2 resolutions). The engine-side code exists on a feature branch but is gated, unmerged, and undeployed; the Cloud control-plane surface (consent, validate, rotate, remove) lives on its own separate branch and is not yet built. The feature is awaiting Seth security gate (S-1 through S-8) and Quinn quality gate (QG-1 through QG-9) clearance before it merges and ships.

The three design principles in this post are the commitments we are testing against. If any of them cannot be verified end-to-end during gate review, the feature does not ship.

This is what design-in-public means for us: sharing the constraints and the reasoning before the code exists, so the community can hold us to them.

HelaSyn Cloud is currently in testnet. BYO-Gemini is a planned v1.1 feature and is not yet available.