# DarrxScale Workspace Agent

[![PyPI](https://img.shields.io/pypi/v/darrxscale-workspace-agent)](https://pypi.org/project/darrxscale-workspace-agent/)
[![Python](https://img.shields.io/pypi/pyversions/darrxscale-workspace-agent)](https://pypi.org/project/darrxscale-workspace-agent/)

A standalone tool execution engine that runs on your machine. Receives tool commands from the DarrxScale backend via WebSocket, executes them locally, and returns results.

## Install

```bash
pip install darrxscale-workspace-agent
```

## Quick Start

```bash
# Get your token from the DarrxScale Workspace Hub
workspace-agent --server wss://your-server.com --token dt_ws_your_token --workspace ~/projects
```

Or with Python module:

```bash
python -m agent_runtime --server wss://your-server.com --token dt_ws_your_token --workspace ~/projects
```

## Docker

```bash
docker run -d \
  --name workspace-agent \
  -v ~/projects:/workspace \
  -e TOKEN=dt_ws_your_token \
  -e SERVER=wss://your-server.com \
  darrxscale/workspace-agent:latest
```

## What It Does

- **Executes tools locally**: filesystem, shell, browser, Android, web fetch, email
- **Service API calls**: receives credential-less specs from backend, resolves credentials from local encrypted vault
- **Credentials stay local**: entered in the frontend, synced to your machine, never stored on servers
- **Multi-agent**: one instance serves all your agents — configure routing from the frontend

## Architecture

```
Frontend (control plane)
    ↓ WSS
Backend (LLM + orchestration)
    ↓ WSS
Workspace Agent (your machine)
    → Local tools (file, shell, browser)
    → Service executor (vault → inject creds → HTTP)
    → Encrypted credential vault
```

## Configuration

| Env Var | Default | Description |
|---------|---------|-------------|
| `TOKEN` | (required) | Auth token from the frontend |
| `SERVER` | `wss://localhost:8000` | Backend WSS URL |
| `WORKSPACE_PATH` | `/workspace` | Working directory |
| `LOG_LEVEL` | `INFO` | Logging level |
| `AUDIT_LEVEL` | `full` | Audit detail: `full`, `summary`, `errors_only` |

## Optional Extras

```bash
# Browser automation (Playwright)
pip install darrxscale-workspace-agent[browser]

# Android automation
pip install darrxscale-workspace-agent[android]

# Everything
pip install darrxscale-workspace-agent[all]
```

## Self Test

```bash
workspace-agent --self-test
```

## Security

- **Encrypted vault**: credentials stored with AES-256-GCM, key derived from your token
- **Per-agent limits**: filesystem restrictions, command allowlists, rate limits
- **Audit trail**: every tool execution logged as structured JSON to stdout
