devX

Documentation

AGENTS.md

Devex Agent Guide

Summary Devex is a cloud development IDE with sandboxed “repl” sessions. The system is split into services. The core service handles auth and session orchestration, while the runner provides the interactive sandbox (WebSocket + PTY). Session data is persisted to S3-compatible storage when a repl is deactivated.
Architecture (High Level)
  • •Core service (apps/core) is deployed to a VPS via Docker Swarm and is the control plane.
  • •Runner service (apps/runner) is the data plane sandbox image. Each repl is a Kubernetes Deployment with a single pod.
  • •Pod layout:
    • •initContainer pulls workspace files from S3.
    • •runnerContainer is the interactive sandbox (WebSocket + PTY).
  • •Deactivation flow:
    • •Core injects an ephemeral container into the pod to upload workspace data to S3.
    • •Core then deletes Deployment/Service/Ingress/Middleware.
  • •Routing:
    • •Base host: repl.parthkapoor.me
    • •Route pattern: repl.parthkapoor.me/<repl-id>/<route>
    • •Uses hostNetwork: true to avoid a load balancer and save cost.
Key Entry Points
  • •Core API: apps/core/cmd/main.go
  • •Runner API: apps/runner/cmd/main.go
  • •MCP service: apps/mcp/cmd/main.go
Repo Layout
  • •apps/core/: Control-plane service (auth + session orchestration + k8s + s3 + redis).
  • •apps/runner/: Sandbox service (WebSocket, PTY, file operations, shutdown manager).
  • •apps/mcp/: MCP server.
  • •apps/web/: Frontend web app.
  • •apps/agent/: Agent-related app (check README inside).
  • •packages/: Shared Go packages and generated protobufs.
    • •packages/logging: Shared logger wrapper.
    • •packages/proto + packages/pb: Proto sources and generated code.
  • •infra/: Deployment and infrastructure.
    • •infra/core/: Swarm dockerfile + stack config.
    • •infra/runner/: Runner dockerfiles (base + language variants).
    • •infra/mcp/: MCP dockerfile.
    • •infra/k8s/: K8s manifests, cert-manager, ingress, traefik.
  • •templates/: Repl templates synced to object storage.
Data Stores
  • •Redis: repl/session state.
  • •S3-compatible storage: workspace persistence on session end.
Build and Test (Local)
  • •Core build:
    • •cd apps/core
    • •go build -o /tmp/core ./cmd/main.go
  • •Runner build:
    • •cd apps/runner
    • •go build -o /tmp/runner ./cmd/main.go
  • •Docker images:
    • •docker build -f infra/core/dockerfile -t devex/core:local .
    • •docker build -f infra/runner/dockerfile -t devex/runner:local .
CI/CD
  • •Workflows live in .github/workflows/.
  • •Core pipeline builds/pushes and deploys via Docker Swarm.
  • •Runner pipeline builds runner + env images.
  • •Templates pipeline syncs templates/ to DigitalOcean Spaces.
Where to Look First
  • •Auth/session logic: apps/core/services/auth/
  • •Repl lifecycle: apps/core/services/repl/ and apps/core/internal/k8s/
  • •Runner WS/PTY: apps/runner/pkg/ws/, apps/runner/pkg/pty/
  • •Shared logging: packages/logging/
Notes for Agents
  • •The system relies on hostNetwork: true for simplicity and cost.
  • •The core service is the orchestrator; runner instances are ephemeral and created per repl session.
  • •If you change protobufs in packages/proto/, regenerate via make generate-proto.