Metadata-Version: 2.4
Name: sandbox-engine-cli
Version: 1.0.1
Summary: A CLI tool to run Python projects in sandboxed environments.
Home-page: https://github.com/VivanRajath/sandbox-engine
Author: Vivan Rajath
Author-email: vivanrajath999@gmail.com
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Dynamic: author
Dynamic: author-email
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: requires-python
Dynamic: summary

<div align="center">
  <h1>🛡️ Sandbox Engine</h1>
  <p><b>A fast, lightweight, and secure CLI tool for running Python projects in isolated environments.</b></p>

  <a href="https://pypi.org/project/sandbox-engine-cli/"><img src="https://img.shields.io/pypi/v/sandbox-engine-cli.svg" alt="PyPI version"></a>
  <a href="https://pypi.org/project/sandbox-engine-cli/"><img src="https://img.shields.io/pypi/pyversions/sandbox-engine-cli.svg" alt="Python Versions"></a>
  <a href="https://github.com/VivanRajath/sandbox-engine"><img src="https://img.shields.io/github/license/VivanRajath/sandbox-engine.svg" alt="License"></a>
</div>

---

## 🚀 Overview

`sandbox-engine` allows developers to instantly spin up Python applications (like FastAPI, Django, Flask, Streamlit) without messing up their global environment or touching their local project files. 

It automatically detects your framework, analyzes your code to dynamically generate required dependencies, strictly isolates the execution environment, and cleans up the sandbox the moment you exit.

## 📦 Installation

Install globally using `pip`:

```bash
pip install sandbox-engine-cli
```

*(Note: The PyPI package is named `sandbox-engine-cli`, but the terminal command is `sandbox-engine`).*

## 🛠️ Core Commands

Navigate to any existing Python project directory and run:

### `scan`
Instantly analyzes the project structure.
- Discovers all Python files.
- Locates potential application entrypoints (e.g., `app.py`, `main.py`).
- Identifies existing virtual environments and dependency management files.

```bash
sandbox-engine scan
```

### `detect`
Intelligently infers your application architecture.
- Auto-detects the web framework (Flask, FastAPI, Django, Streamlit, Gradio).
- Identifies the exact port the application intends to use.
- **Deep AST Analysis:** Scans your code to find all third-party imports, filtering out over 150 standard library modules to figure out exactly what your app needs to run.

```bash
sandbox-engine detect
```

### `run`
Standard execution with dependency injection.
- Scans your imports and cross-verifies them against your existing `requirements.txt`.
- Automagically appends missing dependencies.
- Sets up a standard virtual environment (`venv`) and runs the application.

```bash
sandbox-engine run
```

### `run --isolated` (Recommended)
**Zero-mutation execution.** The safest way to test an untrusted or messy project.
- Creates a temporary, hidden `.sandbox` environment.
- Dynamically generates a `requirements.txt` internal to the sandbox.
- Safely installs dependencies strictly within the isolated environment.
- Runs the application securely.
- **Graceful Teardown:** pressing `Ctrl+C` immediately kills the spawned processes and destroys the sandbox directory, leaving your project cleanly exactly how you found it.

```bash
sandbox-engine run --isolated
```

## 🤝 Contributing
Contributions, issues, and feature requests are always welcome! Feel free to check the [issues page](https://github.com/VivanRajath/sandbox-engine/issues).

---
<div align="center">
  Built with ❤️ in Go & Python
</div>
