> ## Documentation Index
> Fetch the complete documentation index at: https://acm-aa28ebf6.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Backend Setup

> Set up local development environment for Go server and Python CLI

## Prerequisites

Install the required tools for backend development:

<CardGroup cols={2}>
  <Card title="Go 1.26+" icon="golang" color="#00ADD8">
    [golang.org/dl](https://golang.org/dl)
  </Card>

  <Card title="Python 3.11+" icon="python" color="#3776AB">
    [python.org/downloads](https://python.org/downloads)
  </Card>

  <Card title="Git" icon="git-alt" color="#F05032">
    [git-scm.com](https://git-scm.com)
  </Card>

  <Card title="Node.js 18+" icon="node-js" color="#339933">
    For `wrangler` CLI - [nodejs.org](https://nodejs.org)
  </Card>
</CardGroup>

## Quick Start

<Steps>
  <Step title="Clone Repository">
    Clone the SuperBox backend repository:

    ```bash theme={null}
    git clone https://github.com/areebahmeddd/superbox.ai.git
    cd superbox.ai
    ```
  </Step>

  <Step title="Create Virtual Environment">
    Create and activate a Python virtual environment:

    **Windows (PowerShell):**

    ```powershell theme={null}
    python -m venv .venv
    .\.venv\Scripts\Activate.ps1
    ```

    **macOS/Linux:**

    ```bash theme={null}
    python3 -m venv .venv
    source .venv/bin/activate
    ```
  </Step>

  <Step title="Install Python CLI">
    Install SuperBox CLI with dependencies:

    ```bash theme={null}
    python -m pip install -e .[cli]
    ```

    **Optional (dev tools):**

    ```bash theme={null}
    python -m pip install -e .[dev]
    ```
  </Step>

  <Step title="Configure Environment">
    Create `.env` file in your working directory:

    ```bash theme={null}
    # 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
    ```

    <Warning>
      Never commit `.env` to version control. Keep credentials secure.
    </Warning>
  </Step>

  <Step title="Run Go Server">
    Navigate to server directory and run:

    **From `src/superbox/server`:**

    ```bash theme={null}
    cd src/superbox/server
    go run .
    ```

    **Or build and run:**

    ```bash theme={null}
    go build -o server.exe .
    .\server.exe
    ```

    Server will be available at:

    * Health: [http://127.0.0.1:8000/health](http://127.0.0.1:8000/health)
    * API: [http://127.0.0.1:8000/api/v1](http://127.0.0.1:8000/api/v1)
  </Step>
</Steps>

## Using the CLI

After setup, verify CLI works:

```bash theme={null}
superbox --help
```

Initialize a project:

```bash theme={null}
superbox init
```

Authenticate (if needed):

```bash theme={null}
superbox auth login
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Missing .env" icon="file">
    Ensure `.env` exists in your working directory with required Cloudflare R2, Firebase, Scanner, and Payment credentials.
  </Accordion>

  <Accordion title="R2 Access Denied" icon="cloud">
    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`.
  </Accordion>

  <Accordion title="Sonar Scanner" icon="shield-check">
    Install `sonar-scanner` CLI and set `SONAR_TOKEN` and `SONAR_ORGANIZATION` in `.env`.
  </Accordion>

  <Accordion title="ggshield/Bandit" icon="lock">
    Install these tools (`ggshield`, `bandit`) if running security scans via `superbox push`.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="CLI Commands" icon="terminal" href="/cli/introduction">
    Learn all CLI commands
  </Card>

  <Card title="API Reference" icon="book" href="/api/introduction">
    Explore HTTP API endpoints
  </Card>

  <Card title="Architecture" icon="sitemap" href="/backend/architecture">
    Understand system design
  </Card>

  <Card title="Deployment" icon="rocket" href="/backend/deployment">
    Deploy to production
  </Card>
</CardGroup>

<Info>
  For complete setup instructions, visit [https://superbox.1mindlabs.org/docs](https://superbox.1mindlabs.org/docs)
</Info>