FullStack Agent - AI-Powered Full-Stack Development Platform

🚀 Overview

You only need to create a sandbox, and then you can start coding with Claude Code; FullstackAgent has already taken care of everything else for you.

This includes:

• Creating a Next.js and shadcn/ui coding environment.
• Creating a PostgreSQL database, configuring the database connection information environment variable.
• Configuring all necessary Claude Code environment variables
• And creating an accessible domain name.

✨ Key Features

The FullstackAgent project is designed to streamline the entire full-stack development lifecycle using an AI-centric approach. Its core capabilities are delivered through a highly orchestrated, self-contained development sandbox:

• Pre-Configured AI Development Environment:

  • A complete, immediately usable development environment is provisioned, featuring Next.js, shadcn/ui, and the Claude Code CLI.
  • Essential AI-related environment variables (e.g., BASE_URL, KEY, etc.) are automatically configured and injected, allowing the AI agent to begin coding instantly without manual setup.

• Isolated PostgreSQL Database Provisioning:

  • A dedicated and isolated PostgreSQL database instance is automatically created for each project using KubeBlocks.
  • The database connection string is securely injected into the development environment as an environment variable (DATABASE_URL), ensuring the AI can access and configure the persistence layer.

• Automated Public Endpoint and Domain Mapping:

  • Multiple accessible subdomains are automatically allocated and managed (HTTPS ingress with SSL termination).
  • These subdomains are configured to map to the specific application ports you wish to expose (e.g., ports 3000, 5000, 8080), providing immediate external access for testing and live development.

• Natural Language Interaction via Web Terminal:

  • All core development and configuration tasks are performed through a built-in Web Terminal (ttyd) using natural language instructions.
  • This provides a direct, low-friction interface for interacting with the AI engineer, receiving code, running commands, and monitoring the development process.

• AI-Aware Business Configuration:

  • Specific business configurations, such as OAuth settings (e.g., GitHub authentication) and Payment configurations, can be fed into the platform.
  • This configuration metadata is made accessible as contextual prompts, allowing the Claude Code agent to intelligently perceive and implement corresponding features (e.g., configuring NextAuth) directly into the generated code.

• Seamless GitHub Repository Integration:

  • The platform is designed for easy association with an external GitHub repository.
  • This facilitates standard code repository management, version control, and collaboration by connecting the AI's generated code to your preferred source control workflow.

• Automated High-Availability Deployment:

  • Projects can be automatically deployed from the development sandbox to a high-availability production environment, leveraging the underlying Kubernetes infrastructure.
  • This aims to abstract away the complexities of deployment, allowing the AI to manage the transition from development to live application.

🏗️ Architecture

System Architecture

                                                                        ┌─────────────────┐                             
                                                                        │ Ingress Domain  │                             
                                                                        └─────────────────┘                             
                                                                                │                                           
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐  
│                 │     │                 │     │                 │     │  Sandbox Pods   │  
│   Web Browser   │────▶│ FullstackAgent  │────▶│   Kubernetes    │────▶│  (with Claude)  │  
│                 │     │                 │     │     Cluster     │     └─────────────────┘
└─────────────────┘     └─────────────────┘     └─────────────────┘             │                       
                               │                         │                      │                      
                               │                         ▼                      │                      
                               │                 ┌─────────────────┐            │                      
                               │                 │   PostgreSQL    │────────────┘
                               │                 └─────────────────┘
                               ▼                         
                        ┌─────────────────┐     
                        │     GitHub      │     
                        │  Repositories   │     
                        └─────────────────┘     

🛠️ Technology Stack

Frontend

• Framework: Next.js 15.5.4 (App Router)
• Language: TypeScript
• Styling: Tailwind CSS v4
• UI Components: Shadcn/UI
• State Management: React Hooks

Backend

• Runtime: Node.js
• API: Next.js API Routes
• Database ORM: Prisma
• Authentication: NextAuth v5 with GitHub OAuth

Infrastructure

• Container Orchestration: Kubernetes
• Database: PostgreSQL (via KubeBlocks)
• Web Terminal: ttyd
• Container Image: fullstack-web-runtime (Custom Docker image with development tools)

📦 Installation

Prerequisites

• Node.js 20.x or higher
• PostgreSQL database
• Kubernetes cluster with KubeBlocks installed
• GitHub OAuth application credentials

Environment Setup

1. Clone the repository:

git clone https://github.com/FullstackAgent/FullstackAgent.git
cd FullstackAgent

2. Install dependencies:

cd fullstack-agent
npm install

3. Set up environment variables:

Create .env.local file:

# Database
DATABASE_URL="postgresql://user:password@localhost:5432/fullstackagent"

# GitHub OAuth
GITHUB_CLIENT_ID="your-github-client-id"
GITHUB_CLIENT_SECRET="your-github-client-secret"

# NextAuth
NEXTAUTH_URL="http://localhost:3000"
NEXTAUTH_SECRET="your-nextauth-secret"

# Kubernetes
KUBECONFIG_PATH="./.secret/kubeconfig"

4. Set up Kubernetes configuration:

Place your kubeconfig file in .secret/kubeconfig

5. Set up Claude Code environment:

Create .secret/.env file with your Anthropic API credentials:

ANTHROPIC_API_KEY="your-anthropic-api-key"

6. Initialize the database:

npx prisma generate
npx prisma db push

7. Run the development server:

npm run dev

Open http://localhost:3000 to access the application.

Database Schema

model User {
  id            String    @id @default(cuid())
  email         String    @unique
  name          String?
  image         String?
  githubId      String    @unique
  accessToken   String?   // Encrypted
  projects      Project[]
  createdAt     DateTime  @default(now())
  updatedAt     DateTime  @updatedAt
}

model Project {
  id                   String                @id @default(cuid())
  name                 String
  description          String?
  githubRepo           String?
  status               String                @default("active")
  databaseUrl          String?
  userId               String
  user                 User                  @relation(fields: [userId], references: [id], onDelete: Cascade)
  sandboxes            Sandbox[]
  environmentVariables EnvironmentVariable[]
  createdAt            DateTime              @default(now())
  updatedAt            DateTime              @updatedAt
}

model Sandbox {
  id                String   @id @default(cuid())
  projectId         String
  project           Project  @relation(fields: [projectId], references: [id], onDelete: Cascade)
  k8sNamespace      String
  k8sDeploymentName String
  k8sServiceName    String
  publicUrl         String?
  ttydUrl           String?
  status            String
  createdAt         DateTime @default(now())
  updatedAt         DateTime @updatedAt
}

🚢 Deployment

Kubernetes Resources

The platform creates the following Kubernetes resources for each project:

1. Database Cluster (KubeBlocks):

   • PostgreSQL 14.8.0
   • 3Gi storage
   • Auto-generated credentials

2. Sandbox Deployment:

   • Custom fullstack-web-runtime image
   • Claude Code CLI pre-installed
   • Web terminal (ttyd) on port 7681
   • Application ports: 3000, 5000, 8080

3. Services & Ingress:

   • Internal service for pod networking
   • HTTPS ingress with SSL termination
   • WebSocket support for terminal

Resource Limits

Default resource allocation per sandbox:

• CPU: 200m limit, 20m request
• Memory: 256Mi limit, 25Mi request
• Storage: 3Gi for database

🔧 Development

Project Structure

fullstack-agent/
├── app/                    # Next.js App Router pages
│   ├── api/               # API routes
│   ├── projects/          # Project management pages
│   └── layout.tsx         # Root layout
├── components/            # React components
│   ├── ui/               # Shadcn/UI components
│   └── ...               # Feature components
├── lib/                   # Core libraries
│   ├── auth.ts           # NextAuth configuration
│   ├── db.ts             # Prisma client
│   ├── kubernetes.ts     # Kubernetes service
│   └── github.ts         # GitHub integration
├── prisma/               # Database schema
├── yaml/                 # Kubernetes templates
└── public/               # Static assets

Key Services

KubernetesService (lib/kubernetes.ts)

• Manages all Kubernetes operations
• Creates databases and sandboxes
• Handles pod lifecycle management

Authentication (lib/auth.ts)

• GitHub OAuth integration
• Session management
• User authorization

Database (lib/db.ts)

• Prisma ORM configuration
• Connection pooling

📚 API Documentation

Sandbox Management

Create Sandbox

POST /api/sandbox/[projectId]
Content-Type: application/json

{
  "envVars": {
    "KEY": "value"
  }
}

Get Sandbox Status

GET /api/sandbox/[projectId]

Delete Sandbox

DELETE /api/sandbox/[projectId]

Project Management

Create Project

POST /api/projects
Content-Type: application/json

{
  "name": "project-name",
  "description": "Project description"
}

🔒 Security

• Authentication: GitHub OAuth ensures only authorized users can access the platform
• Isolation: Each sandbox runs in its own Kubernetes namespace
• Secrets Management: Sensitive data stored in Kubernetes secrets
• Network Policies: Sandboxes isolated from each other
• Resource Limits: Prevents resource exhaustion attacks

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Setup

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests: npm test
5. Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Anthropic for Claude Code
• Sealos for Kubernetes platform
• ttyd for web terminal

📞 Contact

• GitHub: @fanux
• Issues: GitHub Issues

---

100% AI-generated code. Prompted by fanux. Thanks for Claude code & Opus & Sonnet 4.5 & GLM