CyborgShell - Architecture and Security
Overview
CyborgShell is a browser-first AI platform with a fundamentally different architecture than traditional cloud AI tools. This document explains how it works and why it matters for your privacy and security.
Architecture Design
What Runs Where
Your Browser (Client)
- JavaScript Execution
- Transformer Pipeline Processing
- AI API Calls (direct to providers)
- Project Management
- Local Storage (API keys, sessions, configs)
CyborgShell Server (Minimal)
- File load/save operations
- Directory listings
- Optional CORS proxy
- NO code execution
- NO API key storage
Key Principle: Client-Side Execution
Your browser does all the work:
- JavaScript code execution
- Transformer pipeline orchestration
- AI API calls (directly from browser to AI providers)
- Data processing
- Project state management
The server only handles:
- Loading files you request
- Saving files you create
- Listing your saved files
- Optional CORS proxy for some providers
Security Model
API Key Storage
Your API keys are stored in browser local storage:
- ✅ Never transmitted to CyborgShell servers *
- ✅ Never stored in CyborgShell databases
- ✅ Persist across sessions on the same browser
- ✅ Can be backed up/deployed to other machines via csconfig
* unless you use the Cyborg Shell's optional CORS proxy server
Coming Soon: ZOSCII Information Theoretic Security (ITS) Encoding
- Local storage will use ZOSCII
Important: Local storage is tied to the browser/device. If using a public computer:
- Use private/incognito mode, OR
- Clear your config after use:
csconfig → Delete service details
Data Flow
| Architecture |
Traditional Cloud AI |
CyborgShell |
| API Keys |
Stored on vendor servers |
Browser local storage only |
| Code Execution |
On vendor servers |
In your browser |
| AI Calls |
Through vendor server |
Direct from browser |
| Data Privacy |
Vendor sees everything |
Only file operations |
Why This Matters
Privacy:
- Your code never passes through CyborgShell servers during execution
- Your API keys never leave your browser *
- Your AI conversations go directly to the provider *
- CyborgShell never sees your prompts or responses *
* unless you use the Cyborg Shell's optional CORS proxy server
Security:
- Reduced attack surface (no server-side execution)
- No centralized API key database to compromise
- You control which AI providers to use
- Audit trail is simpler (file operations only)
Control:
- Switch AI providers without changing platform
- Use multiple providers simultaneously
- Control costs directly (your API accounts)
- No vendor lock-in
The CORS Proxy
Why It Exists
Browsers have a security feature called CORS (Cross-Origin Resource Sharing) that prevents JavaScript from making requests to different domains. Some AI providers also require authentication tokens in specific formats.
What It Actually Does
The proxy is minimal PHP code (~200 lines) included in the GitHub repository:
// Source/Destination Whitelists
$arrSourceWhitelist = array('cyborgshell.com', 'cyborgdesktop.com', 'localhost');
$arrDestinationWhitelist = array(); // Empty = allow all (you can restrict)
// Logging (OFF by default)
DEFINE('LOG_OUTPUT', 'FALSE');
// Bearer Token Extraction
// Extract bearer token from JSON body
// Remove it from payload before sending to API
// Add proper Authorization: Bearer header
// Forward request to AI provider
Process:
- Receives request from browser with API key in JSON body
- Extracts
bearer or api_key field from JSON
- Removes it from the payload
- Adds proper
Authorization: Bearer header
- Forwards request to AI provider
- Returns response unchanged
What It Doesn't Do
- ❌ Does NOT store your API keys (passed through only)
- ❌ Does NOT retain any data (logging disabled by default)
- ❌ Does NOT execute any code from requests
- ❌ Does NOT modify your prompts or responses
- ❌ Does NOT connect to anything except specified destination
- ❌ Does NOT make outbound calls without explicit request
The Reality of Proxies
Any proxy sees data in transit - that's how proxies work. The critical questions are:
- What does it do with the data? (This one: passes through, doesn't store)
- Can you verify that? (Yes: ~200 lines of open source PHP)
- Can you trust it? (Self-host = you control it completely)
The Truth: If you're using ANY platform with closed-source code, you're trusting them with your API keys whether they admit it or not. CyborgShell's difference:
- ✅ Open Source - Audit every line of code
- ✅ Self-Hostable - Run on your infrastructure
- ✅ Transparent - No hidden data collection
- ✅ Optional - Eliminate proxy entirely with Ollama
Simple Decision Guide
API key visibility through proxy matters to you?
→ Self-host it. Then you control everything. Problem solved.
Don't want to deal with any proxy at all?
→ Use Ollama. Zero external calls, zero proxy needed.
Using cyborgshell.com for convenience?
→ Our server follows best practices. Code is open source. You decide your trust level.
Bottom line: You have options. Choose what fits your security requirements.
Deployment Scenarios
1. Public Cloud (cyborgshell.com)
Architecture: User Browser → cyborgshell.com (file ops) → AI Provider APIs
Use Case: Quick start, multi-device access, cloud storage
Security: API keys in browser, direct API calls to providers
Internet: Required for AI providers, file sync
2. Self-Hosted + Cloud AI
Architecture: User Browser → Your Server (file ops) → Cloud AI APIs
Use Case: Corporate deployment with cloud AI
Security: Full control of server, API keys stay client-side
Setup: Clone from GitHub, host on internal/external server
3. Self-Hosted + Local AI (Complete Privacy)
Architecture: User Browser → Your Server (file ops) → Ollama (localhost)
Use Case: Maximum security, HIPAA/SOC2, air-gapped environments
Security: Zero external data transmission
Perfect For: Healthcare, legal, financial, classified work
4. Distributed Processing (Horizontal Scaling)
Architecture: Shared Network Drive → Multiple PCs with Ollama processing in parallel
Use Case: Batch processing, render farms, massive throughput
Benefits:
- Zero cost (all Ollama local)
- Horizontal scaling (add more PCs = more throughput)
- Minimal server load (only file I/O)
- Natural load balancing
- Fault tolerant
- MapReduce-style AI processing
Compliance & Enterprise
HIPAA (Healthcare)
Requirements: PHI must not leave network
CyborgShell Solution:
- Self-host CyborgShell internally
- Use Ollama for any PHI-related processing
- No PHI ever transmitted externally
- Server logs only file operations (no content)
- Encryption via HTTPS (your cert)
SOC 2 (Service Organizations)
CyborgShell Solution:
- Simple data flow (browser → your server → local AI)
- No third-party data processing
- Audit trail limited to file operations
- Open source allows security review
GDPR (Privacy)
CyborgShell Solution:
- Minimal server-side data (files only)
- User controls all API keys and configs
- No user tracking or analytics in code
- Simple deletion (remove files)
Technical Details
Server Requirements (Self-Hosting)
Minimal:
- Any web server (Apache, Nginx, IIS)
- PHP (for file functionality and optional CORS proxy)
No Special Requirements:
- No database
- No application server
- No containers required (but can use)
- Static HTML/JS + simple file ops
Network Requirements
| Deployment |
Requirements |
| Public Cloud |
Internet access for AI provider APIs, HTTPS |
| Self-Hosted + Cloud AI |
Outbound access to AI providers, inbound for users |
| Self-Hosted + Local AI |
No internet required at all, internal network only |
Security Best Practices
API Key Management
DO:
- Use csconfig to set keys (stores in browser local storage)
- Back up your config (csconfig → BL → Backup configuration to Local Download)
- Use different keys per environment (dev/prod)
DON'T:
- Share devices with sensitive keys (use private/incognito if needed)
- Commit keys to version control (projects don't contain keys)
Proxy Configuration
- Keep
LOG_OUTPUT = 'FALSE' in production
- Enable logging only for troubleshooting specific issues
- Set restrictive source/destination whitelists
- Use HTTPS for all connections
- Review logs immediately after debugging, then delete
- Consider eliminating proxy entirely (use Ollama local)
Advantages of This Architecture
For Users
- ✅ Privacy: Your code, your keys, your control
- ✅ Flexibility: Switch AI providers anytime
- ✅ Cost: Your API keys = your pricing
- ✅ Speed: Direct API calls, no intermediary
- ✅ Offline: Works with local AI (Ollama)
For Organizations
- ✅ Security: Reduced attack surface
- ✅ Compliance: Air-gap capable
- ✅ Control: Self-host everything
- ✅ Audit: Simple data flows
- ✅ Cost: No platform fees
For Developers
- ✅ Transparency: Open source (MIT)
- ✅ Extensibility: Add your own transformers
- ✅ Portability: Run anywhere
- ✅ Simplicity: Static files + file ops
- ✅ Customization: Fork and modify
Source Code and Open Source License
Conclusion
CyborgShell's browser-first architecture provides unique security and privacy benefits:
- Your API keys stay local (browser storage, not servers)
- Your code executes in your browser (not on servers)
- Your AI calls go direct (browser → AI provider)
- Complete self-hosting possible (MIT license)
- Air-gap capable (with Ollama)
Whether you use the public cloud version for convenience, self-host for control, or deploy air-gapped for maximum security - the choice is yours.
Your code. Your AI. Your control. 🔒