Files · xAI Grok Secure Code Sandbox for SMB Data Pipelines

# xAI Grok Secure Code Sandbox for SMB Data Pipelines
 
> Empower SMBs to safely run AI-generated code on their data with cost controls and execution quarantine, preventing runaway bills and destructive operations.
 
A tutorialized reference solution from [reaatech.com](https://reaatech.com), demonstrating how to build production-grade AI systems with the `@reaatech/*` package family.
 
## Architecture
 
```
User prompt
    │
    ▼
1. LLM Code Generation (xAI Grok via @ai-sdk/openai-compatible)
    │
    ▼
2. Structured Output Repair (@reaatech/structured-repair-core)
    │
    ▼
3. Policy Firewall Preflight (@reaatech/tool-use-firewall-core)
    │
    ├── BLOCK ──────────────► 403 PolicyViolationError
    ├── APPROVAL_REQUIRED ──► 202 Approval Required (stored for review)
    └── ALLOW
          │
          ▼
4. Budget Check (@reaatech/agent-budget-engine)
    │
    ├── Deny ──────────────► 402 Budget Exceeded
    └── Allow
          │
          ▼
5. Sandbox Execution (E2B)
    │
    ▼
6. Result + Spend Recording + Telemetry (Langfuse)
```
 
## Environment Variables
 
| Variable | Required | Default | Description |
|---|---|---|---|
| `XAI_API_KEY` | Yes | — | xAI API key for Grok model access |
| `E2B_API_KEY` | Yes | — | E2B sandbox API key |
| `LANGFUSE_PUBLIC_KEY` | No | — | Langfuse observability public key |
| `LANGFUSE_SECRET_KEY` | No | — | Langfuse observability secret key |
| `LANGFUSE_BASE_URL` | No | `https://cloud.langfuse.com` | Langfuse API base URL |
| `DEFAULT_BUDGET_LIMIT` | No | `10.0` | Default user budget limit (USD) |
| `PORT` | No | `3000` | Express server port |
 
## API Endpoints
 
### POST /api/code
 
Execute an AI-generated code snippet from a natural-language prompt.
 
```bash
curl -X POST http://localhost:3000/api/code \
  -H "Content-Type: application/json" \
  -d '{"prompt": "read a CSV and show the first 5 rows", "userId": "user-1"}'
```
 
**Response** (200):
```json
{
  "status": "success",
  "executionId": "uuid",
  "code": "import pandas...",
  "language": "python",
  "result": { "stdout": "...", "stderr": "", "exitCode": 0, "executionTimeMs": 120 },
  "cost": 0.01,
  "model": "grok-3"
}
```
 
**Error responses**: `400` (missing fields), `402` (budget exceeded), `403` (policy violation), `202` (approval required), `500` (internal).
 
### GET /api/code?userId=...
 
Fetch execution history for a user.
 
```bash
curl "http://localhost:3000/api/code?userId=user-1"
```
 
### GET /api/budget?userId=...
 
Fetch budget state for a user.
 
```bash
curl "http://localhost:3000/api/budget?userId=user-1"
```
 
**Response** (200):
```json
{ "spent": 1.5, "remaining": 8.5, "state": "Active" }
```
 
### GET /api/approvals
 
List pending approval requests.
 
```bash
curl http://localhost:3000/api/approvals
```
 
### POST /api/approvals
 
Approve or reject a pending request.
 
```bash
curl -X POST http://localhost:3000/api/approvals \
  -H "Content-Type: application/json" \
  -d '{"requestId": "uuid", "action": "approve"}'
```
 
```bash
curl -X POST http://localhost:3000/api/approvals \
  -H "Content-Type: application/json" \
  -d '{"requestId": "uuid", "action": "reject", "reason": "not needed"}'
```
 
## Policy YAML Format
 
The default policy is loaded from `policies/default.yaml`:
 
```yaml
allowedLibraries:
  - pandas
  - numpy
  - openpyxl
  - csv
  - json
  - re
  - math
  - statistics
  - datetime
  - collections
  - itertools
  - functools
maxExecutionTimeMs: 30000
blockedPatterns:
  - subprocess
  - os\\.system
  - shutil\\.rmtree
  - eval\\(
  - exec\\(
  - open\\([^/]
```
 
- **allowedLibraries**: Python modules the generated code may import. Imports outside this list are blocked.
- **maxExecutionTimeMs**: Maximum wall-clock time for sandbox execution (milliseconds).
- **blockedPatterns**: Regex patterns scanned against generated code. Any match blocks execution.
 
## Running locally
 
```bash
pnpm install
pnpm test            # vitest run with coverage
pnpm dev             # next dev
pnpm lint            # eslint
pnpm typecheck       # tsc --noEmit
```
 
## Project layout
 
```
app/                  Next.js App Router pages + API routes
src/
  lib/                Config, LLM, repair, budget, sandbox, telemetry, approval, xlsx-utils, policy-loader
  services/           Orchestration (runCodePipeline)
  server.ts           Express server (alternative to App Router)
tests/                vitest suite (mirrors src/)
policies/             YAML policy files
packages/             API references for every dependency
DEV_PLAN.md           build plan for this recipe
```
 
## License
 
MIT — see [LICENSE](./LICENSE).