Backend Setup

Set up local development environment for Go server and Python CLI

Prerequisites

Install the required tools for backend development:

Go 1.26+

golang.org/dl

Python 3.11+

python.org/downloads

Git

git-scm.com

Node.js 18+

For wrangler CLI - nodejs.org

Quick Start

1. Clone Repository

   Clone the SuperBox backend repository:

   git clone https://github.com/areebahmeddd/superbox.ai.git
   cd superbox.ai
   
2. Create Virtual Environment

   Create and activate a Python virtual environment:

   Windows (PowerShell):

   python -m venv .venv
   .\.venv\Scripts\Activate.ps1
   

   macOS/Linux:

   python3 -m venv .venv
   source .venv/bin/activate
   
3. Install Python CLI

   Install SuperBox CLI with dependencies:

   python -m pip install -e .[cli]
   

   Optional (dev tools):

   python -m pip install -e .[dev]
   
4. Configure Environment

   Create .env file in your working directory:

   # SuperBox API
   SUPERBOX_API_URL=http://localhost:8000/api/v1
   
   # Cloudflare account
   CLOUDFLARE_ACCOUNT_ID=your_account_id
   
   # Cloudflare R2 (from Cloudflare dashboard > R2 > Manage R2 API tokens)
   CLOUDFLARE_R2_ENDPOINT=https://<account-id>.r2.cloudflarestorage.com
   CLOUDFLARE_R2_ACCESS_KEY_ID=your_r2_access_key_id
   CLOUDFLARE_R2_SECRET_ACCESS_KEY=your_r2_secret_access_key
   CLOUDFLARE_R2_BUCKET_NAME=superbox-mcp-registry
   
   # Cloudflare Worker URL
   CLOUDFLARE_WORKER_URL=https://superbox-executor.<your-subdomain>.workers.dev
   
   # Firebase (from Firebase Console > Project settings > Service accounts)
   FIREBASE_PROJECT_ID=your_project_id
   FIREBASE_PRIVATE_KEY=your_private_key
   FIREBASE_CLIENT_EMAIL=your_client_email
   
   # Scanners (required for superbox push)
   SONAR_TOKEN=your_sonar_token
   SONAR_ORGANIZATION=your_org
   GITGUARDIAN_API_KEY=your_gitguardian_key
   SNYK_API_TOKEN=your_snyk_api_token
   
   # Payments
   RAZORPAY_KEY_ID=your_razorpay_key_id
   RAZORPAY_KEY_SECRET=your_razorpay_secret
   

   Never commit .env to version control. Keep credentials secure.

5. Run Go Server

   Navigate to server directory and run:

   From src/superbox/server:

   cd src/superbox/server
   go run .
   

   Or build and run:

   go build -o server.exe .
   .\server.exe
   

   Server will be available at:

   • Health: http://127.0.0.1:8000/health
   • API: http://127.0.0.1:8000/api/v1

Using the CLI

After setup, verify CLI works:

superbox --help

Initialize a project:

superbox init

Authenticate (if needed):

superbox auth login

Troubleshooting

Missing .env

Ensure .env exists in your working directory with required Cloudflare R2, Firebase, Scanner, and Payment credentials.

R2 Access Denied

Verify CLOUDFLARE_R2_ACCESS_KEY_ID and CLOUDFLARE_R2_SECRET_ACCESS_KEY are R2 API token credentials (not Cloudflare global API key). Check that the bucket name matches CLOUDFLARE_R2_BUCKET_NAME.

Sonar Scanner

Install sonar-scanner CLI and set SONAR_TOKEN and SONAR_ORGANIZATION in .env.

ggshield/Bandit

Install these tools (ggshield, bandit) if running security scans via superbox push.

Next Steps

CLI Commands

Learn all CLI commands

API Reference

Explore HTTP API endpoints

Architecture

Understand system design

Deployment

Deploy to production

For complete setup instructions, visit https://superbox.1mindlabs.org/docs