← nyxcore-systems
6 min read

Beyond the Tenant: Shipping User-Level BYOK and Demystifying AI Protocols

A deep dive into a recent development session, covering the implementation of user-level Bring Your Own Key (BYOK) fallback, translating complex AI system documentation, and navigating the inevitable deployment hurdles.

BYOKAPI KeysPrismaTypeScriptDockerPostgreSQLDeploymentTechnical WritingAILLMtRPC

Every development sprint has its heroes and its battle scars. This past session was no different. Our mission? To empower users with more granular control over their API keys and to transform our groundbreaking, albeit internally-named, "Ipcha Mistabra" AI protocol documentation into something fit for academic scrutiny. Oh, and of course, get it all deployed to production.

Let's break down the journey, the triumphs, and the critical lessons learned along the way.

Empowering Users: The BYOK Fallback Saga

Our existing system used tenant-level API keys, which worked well for many use cases. However, as we scale and aim for greater flexibility and security, the need for user-level API key management became apparent. Imagine a scenario where a user wants to bring their own OpenAI key, separate from the organization's pooled key, for specific projects or personal insights. That's where Bring Your Own Key (BYOK) comes in, and specifically, a fallback mechanism that prioritizes a user's personal key before defaulting to the tenant-wide key.

Here's how we tackled it:

1. Schema Evolution: The isPersonal Flag

The first step was to differentiate between personal and tenant keys at the data model level. We updated our ApiKey model in prisma/schema.prisma:

prisma
model ApiKey {
  id        String   @id @default(cuid())
  key       String   @unique
  tenantId  String
  // ... other fields
  isPersonal Boolean @default(false) // New field!
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt

  tenant Tenant @relation(fields: [tenantId], references: [id])
}

This simple isPersonal boolean, defaulting to false, ensures that all existing tenant keys remain tenant-wide, while new personal keys can be explicitly marked.

2. Intelligent Key Resolution: Prioritizing User Keys

The core logic resides in our key resolution services. Functions like resolveProvider() (for LLM providers) and resolveGitHubToken() needed to be smarter. They now accept an optional userId and perform a two-stage lookup:

  1. Check for User's Personal Key: If a userId is provided, the system first attempts to find an ApiKey associated with that user and where isPersonal is true.
  2. Fallback to Tenant Key: If no personal key is found for the user, it then falls back to searching for a tenant-wide key (isPersonal: false) for the user's current tenant.

This ensures a seamless experience: users who configure a personal key automatically use it, while others continue to leverage the tenant's shared key without interruption.

3. Admin & API Exposure

To manage these new personal keys, our src/server/trpc/routers/admin.ts router was updated:

  • apiKeys.list now returns the isPersonal status, allowing administrators to see the scope of each key.
  • apiKeys.create accepts an isPersonal parameter, enabling the creation of both personal and tenant-level keys via API.

4. Database Migration: A Moment of Truth (and Pain)

Getting that is_personal column into our production PostgreSQL database was where things got interesting.

The Plan (and its Flaw): We typically use a safe migration script (db-migrate-safe.sh) that sources our .env variables. The Reality:

  • Our production .env file is actually .env.production. A small naming difference, but enough to break the script.
  • More critically, the DATABASE_URL in our Dockerized environment uses the internal hostname postgres:5432. This hostname doesn't resolve from the host machine where the migration script was being run.

The Workaround & Lesson Learned: Instead of fighting with Docker networking and .env files for a simple ALTER TABLE, we opted for a direct approach:

bash
docker exec nyxcore-postgres-1 psql -U <your_user> -d <your_db> -c "ALTER TABLE api_keys ADD COLUMN is_personal BOOLEAN NOT NULL DEFAULT FALSE;"

This executed the ALTER TABLE command directly inside the running PostgreSQL container, bypassing host networking issues.

Lesson Learned: While robust migration scripts are vital, especially for complex schema changes, understanding your production environment's networking and having a direct docker exec fallback is crucial. For production schema changes, always validate that your migration strategy accounts for container isolation and environment variable sourcing. We need to invest in a more robust, container-native migration pipeline for future, more complex schema changes.

Decoding the Intricacies: Ipcha Mistabra Documentation

Beyond the code, a significant chunk of this session was dedicated to knowledge distillation. Our internal "Ipcha Mistabra" protocol, a sophisticated agentic AI system, needed its documentation translated from internal jargon into academia-ready English. This wasn't just about grammar; it was about reframing complex internal concepts for an external, highly critical audience.

We tackled two substantial documents (~34KB and ~33KB each):

  • docs/ipcha-mistabra/ipcha-mistabra-system-persona.md: This document delved into the theoretical underpinnings of the IM protocol, its three-phase architecture, the novel "Ipcha Score" for agent evaluation, and even included a case study (the "Finn escape"). Crucially, it was meticulously referenced with 21 IEEE-format citations, ready for peer review.
  • docs/ipcha-mistabra/technical-implementation.md: This companion piece focused on the practicalities. It detailed the Agentic Science foundation, the Distributed Autonomous (DA) system architecture, efficiency benchmarks, and a thorough cost analysis. It also boasted 19 academic references.

This effort is critical for external communication, potential research collaborations, and establishing the credibility of our AI systems. It's a testament to the fact that building complex systems is only half the battle; articulating their value and mechanics is equally important.

Infrastructure & Deployment Wins (and a Minor Hiccup)

With the code and docs ready, it was time for deployment. The BYOK changes and the Ipcha Mistabra documentation were committed and pushed.

Docker Build Backgrounding

During the build process, I tried to run a docker build command in the background via SSH. The Problem: Immediately checking the output file showed it was empty. The Workaround & Lesson Learned: Re-running the command directly (which also went into the background) and then waiting ~40 seconds before checking the output file revealed a successful build.

Lesson Learned: When backgrounding commands, especially long-running ones like Docker builds, don't expect immediate output. Ensure proper output redirection (e.g., &> build.log &) and always give the process enough time to start and produce output before checking. Better yet, use tools like nohup or screen/tmux for robust background execution and persistent sessions.

Keeping it Lean: Docker Cache Pruning

On a related note, a minor but satisfying win earlier in the day was pruning 73GB of Docker cache on the production server. Keeping the build environment lean and clean is crucial for efficient deployments and resource management.

Wrapping Up and Looking Ahead

This session was a solid stride forward. We've rolled out a critical user-facing feature (BYOK), significantly advanced our external-facing documentation, and navigated some common, yet always tricky, deployment challenges. The production environment is now running on the latest commit (2c2d2cc), and the is_personal column is live in the api_keys table.

The journey continues, and the next steps are already mapped out:

  • Developing a "BookKeyPoints" feature to auto-include insights from books into project wisdom.
  • Adding an {{ethics}} template variable for ethical insights directly from source material.
  • Improving our UI for personal API key management.
  • Further integrating userId for BYOK across our workflow engine and discussion service.
  • Implementing RLS policies for enhanced data security.

Every line of code, every translated paragraph, and every deployment challenge overcome brings us closer to a more robust, intelligent, and user-centric system. It's the authentic developer experience – a blend of meticulous planning, problem-solving, and continuous learning.

json
{"thingsDone":["Implemented user-level BYOK fallback for API keys (isPersonal flag, resolution logic, admin API)","Translated two comprehensive 'Ipcha Mistabra' documents into academic English (protocol theory, technical implementation)","Successfully deployed all changes to production","Added is_personal column to production database"],
"pains":["Production DB migration script failed due to .env path and Docker-internal hostname issues","Backgrounded Docker build command initially appeared to produce empty output"],
"successes":["Successfully applied DB schema change using docker exec psql","Identified and resolved Docker build output issue by waiting for completion","Reclaimed 73GB of Docker cache on production server","Achieved full production deployment"],
"techStack":["Prisma","TypeScript","Docker","PostgreSQL","tRPC","GitHub","LLM (concept)","Bash scripting"]}