Backend Service
wspace-vibecontrols-svc is the VibeControls backend subgraph on the Burdenoff Workspaces platform. It runs as a managed container service in the India region and is federated into the workspace public gateway (wspace-public-gateway) and workspace internal gateway (wspace-int-gateway).
What it does
- Agents — multi-agent orchestration across local and remote machines
- Vibes — hierarchical workspace/project organization
- Sessions — tmux/wezterm/zellij/SSH/terminal/script session management with auto-start
- SSH Connections — SSH connection management with auto-reconnect
- Port Forwarding — local, remote, and dynamic port forwarding
- Notes — rich notes with tagging and pinning
- Prompts — reusable prompt library with variables
- Modules — extension module marketplace with registry
- Configuration — flexible configuration system (global, vibe, session-scoped)
- UI Sessions — UI session state persistence per user
- Webhooks — webhook integrations for event notifications
- VibeDecks — Stream-Deck-style command button grids
- Targets — SSH/RDP/VNC connection destinations
- Tunnels — Cloudflare quick tunnels and VibeTunnels (frp)
- Audit — audit logging for all operations
- AI Tool Events — telemetry from external AI tools
Repo structure
wspace-vibecontrols-svc/
├── src/
│ ├── modules/ # Feature modules
│ │ ├── agent/ # Agent orchestration
│ │ ├── vibe/ # Workspace/vibe management
│ │ ├── session/ # Session management
│ │ ├── ssh/ # SSH connections
│ │ ├── portforward/ # Port forwarding
│ │ ├── note/ # Notes system
│ │ ├── prompt/ # Prompts library
│ │ ├── vibemodule/ # Module marketplace
│ │ ├── configuration/ # Configuration system
│ │ ├── uisession/ # UI session state
│ │ └── webhook/ # Webhook integrations
│ ├── config/ # Configuration
│ ├── generated/ # Generated types
│ └── index.ts # Entry point
├── prisma/ # Prisma schema and migrations
├── docker-compose.yml # State service orchestration
└── package.json # Scripts and dependencies
Environment selection
The service reads its gateway and database endpoints from environment variables. In production it uses:
| Service | Prod endpoint |
|---|---|
| Workspace public gateway | https://graphqlworkspaces.burdenoff.com/workspaces/graphql |
| Workspace internal gateway | https://graphqlworkspaces.burdenoff.com/workspaces/graphql |
| Global public gateway | https://graphql.burdenoff.com/global/graphql |
Local development uses localhost ports (see below).
Quick start (local development)
# Install dependencies
bun install
# Start state services (PostgreSQL + Valkey)
cd ../wspace-vibecontrols-state
docker compose up -d
# Generate Prisma client and GraphQL types
cd ../wspace-vibecontrols-svc
bun run gendb
bun run codegen
# Apply migrations
bun run migrate:deploy
# Start development server
bun run dev
Commands
Development
bun run dev # Start development server with watch mode
bun run dev:docker # Start with docker environment
bun run start # Start production server
Database
bun run migrate # Create new migration
bun run migrate:deploy # Apply migrations
bun run reset # Reset database (force)
bun run db:push # Push schema changes
bun run gendb # Generate Prisma client
Code generation
bun run codegen # Generate GraphQL types
Quality checks
bun run lint # Lint code
bun run lint:fix # Lint and fix issues
bun run format # Format code
bun run format:check # Check code formatting
bun run type:check # TypeScript type checking
bun run test # Run tests
bun run test:watch # Run tests in watch mode
bun run test:coverage # Run tests with coverage
bun run knip # Check for unused dependencies
Build & deploy
bun run build # Build for production
bun run sanity # Run all quality checks (format, lint, type, build, test, knip)
GraphQL Hive
bun run hive:schema # Generate Hive schema
bun run hive:check # Check schema compatibility
bun run hive:dev # Publish to development
bun run hive:publish # Publish to development
bun run hive:publish:staging # Publish to staging
bun run hive:publish:production # Publish to production
bun run hive:clean # Clean Hive artifacts
Technology stack
- Runtime: Bun 1.3.5+
- Language: TypeScript 5.9+
- Framework: Elysiajs + GraphQL Yoga
- GraphQL: Apollo Federation v2, GraphQL Hive Cloud
- Database: PostgreSQL 18+ + Prisma 7.x with AGE graph extension
- Cache / Events: managed Redis-compatible cache (TLS) via
@burdenoff/be-sdk - SDK:
@burdenoff/be-sdk
Environment variables
Key variables (see .env.example and .env.local.example for the full list):
DATABASE_URL— PostgreSQL connection string (TLS required)REDIS_URL— Redis-compatible cache connection string (TLS)WSPACE_INT_GATEWAY_URL— Internal gateway URLGLOBAL_PUBLIC_GATEWAY_URL— Cross-layer gateway URLSERVICE_LAYER— Service layer (wspace)
Architecture
Module structure
Each module contains:
schema/— GraphQL schema definitionsresolvers/— GraphQL resolversservices/— Business logic__tests__/— Unit tests
Layer configuration
This service is part of the wspace (workspace) layer and uses:
- Internal Gateway:
wspace-int-gatewayfor same-layer calls - Cross-Layer Gateway:
global-public-gatewayfor cross-layer calls
Context field
All Prisma models include a context JSON field for multi-dimensional data isolation:
interface EntityContext {
workspace_id: string; // REQUIRED
project_id?: string; // Optional
actor_id?: string; // Optional
organization_id?: string; // Optional
}
Related repositories
- Service:
github.com/algoshred/wspace-vibecontrols-svc - State:
~/products/wspace/vibecontrols/wspace-vibecontrols-state - Specs:
~/products/vibecontrols/vibecontrols-specs/ - E2E Tests:
~/products/vibecontrols/vibecontrols-doctor/
Development workflow
- Start state services:
cd ../wspace-vibecontrols-state && docker compose up -d - Generate types:
bun run codegen && bun run gendb - Apply migrations:
bun run migrate:deploy - Start dev server:
bun run dev - Run tests:
bun run test - Before commit:
bun run sanity
Source
- Repository:
github.com/algoshred/wspace-vibecontrols-svc - Deployed continuously from
mainvia GitHub Actions (alpha, then production)