Metadata-Version: 2.4
Name: podex-pod
Version: 0.0.1a1
Summary: Podex Local Pod - Self-hosted compute agent for Podex
Project-URL: Homepage, https://podex.dev
Project-URL: Documentation, https://docs.podex.dev/local-pods
Project-URL: Repository, https://github.com/podex/podex
Author-email: Podex <support@podex.dev>
License: MIT
Keywords: agent,compute,docker,local-pod,podex
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.11
Requires-Dist: aiofiles>=23.2.0
Requires-Dist: click>=8.1.0
Requires-Dist: docker>=7.0.0
Requires-Dist: httpx>=0.26.0
Requires-Dist: psutil>=7.2.2
Requires-Dist: pydantic-settings>=2.1.0
Requires-Dist: pydantic>=2.5.0
Requires-Dist: python-socketio[asyncio-client]>=5.10.0
Requires-Dist: sentry-sdk>=2.51.0
Requires-Dist: structlog>=24.1.0
Requires-Dist: watchdog>=4.0.0
Provides-Extra: dev
Requires-Dist: mypy>=1.7.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: ruff>=0.14.14; extra == 'dev'
Description-Content-Type: text/markdown

# Podex Local Pod

Self-hosted compute agent for Podex. Run workspaces on your own machine for faster local development, full GPU access, and keeping code on-premises.

## Quick Start

### 1. Get Your Token

1. Go to **Settings > Local Pods** in Podex
2. Click **Add Pod** and give it a name
3. Copy the token (shown only once!)

### 2. Install

```bash
# Using pip
pip install podex-pod

# Or using pipx (recommended)
pipx install podex-pod
```

### 3. Run

```bash
# Start the agent
podex-pod start --token pdx_pod_xxx

# Or use environment variable
export PODEX_POD_TOKEN=pdx_pod_xxx
podex-pod start
```

## Docker Installation (Optional)

You can run the pod agent itself inside Docker:

```bash
docker run -d \
  --name podex-pod \
  -e PODEX_POD_TOKEN=pdx_pod_xxx \
  podex/local-pod:latest
```

## Commands

```bash
# Start the agent
podex-pod start [OPTIONS]

# Check system requirements
podex-pod check

# Show version
podex-pod version
```

### Start Options

| Option    | Environment Variable | Description                                      |
| --------- | -------------------- | ------------------------------------------------ |
| `--token` | `PODEX_POD_TOKEN`    | Pod authentication token (required)              |
| `--url`   | `PODEX_CLOUD_URL`    | Podex cloud URL (default: https://api.podex.dev) |
| `--name`  | `PODEX_POD_NAME`     | Display name for this pod                        |

## Configuration File

Create a `.env` file to save your configuration:

```bash
# ~/.config/podex/.env
PODEX_POD_TOKEN=pdx_pod_xxx
PODEX_POD_NAME=my-dev-machine
PODEX_CLOUD_URL=https://api.podex.dev
```

Then run from that directory:

```bash
cd ~/.config/podex && podex-pod start
```

Or copy the `.env` file to your current working directory.

## Requirements

- Python 3.11+
- tmux (required for terminal features)
- 4GB+ RAM recommended
- 2+ CPU cores recommended

## How It Works

1. **Registration**: You register a local pod in Podex Settings and receive a token
2. **Connection**: The agent connects to Podex cloud via WebSocket (outbound connection)
3. **Commands**: When you create a workspace targeting your local pod, Podex sends commands through the WebSocket
4. **Execution**: The agent executes commands natively on your machine using tmux for terminal sessions
5. **Communication**: File operations, terminal, and port forwarding all work through the connection

## Security

- **Outbound only**: The agent initiates the connection - no inbound ports needed
- **Token auth**: Tokens are hashed and verified on each connection
- **User isolation**: Each pod only sees workspaces for its owner
- **Native execution**: Commands run directly on your machine with your user permissions

## Troubleshooting

### Check Requirements

```bash
podex-pod check
```

This verifies tmux is available and shows system resources.

### Common Issues

**Connection refused**

- Check your internet connection
- Verify the token is correct
- Check if a firewall is blocking outbound WebSocket connections

**tmux not found**

- Install tmux: `brew install tmux` (macOS) or `apt install tmux` (Linux)
- tmux is required for terminal features to work properly

## Development

```bash
# Clone the repo
git clone https://github.com/podex/podex
cd podex/services/local-pod

# Install dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run linting
ruff check .
mypy .
```

## License

MIT License - see [LICENSE](../../LICENSE) for details.
