Metadata-Version: 2.4
Name: arc-relay
Version: 0.1.4
Summary: ARC Relay — WebSocket relay server for agent remote control by Axolotl AI
Author: ARC Contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/axolotl-ai-cloud/arc
Project-URL: Repository, https://github.com/axolotl-ai-cloud/arc
Project-URL: Issues, https://github.com/axolotl-ai-cloud/arc/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.115.0
Requires-Dist: uvicorn[standard]>=0.32.0
Requires-Dist: websockets>=13.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24.0; extra == "dev"
Requires-Dist: httpx>=0.27.0; extra == "dev"
Requires-Dist: starlette[full]>=0.41.0; extra == "dev"
Dynamic: license-file

# ARC — Agent Remote Control

Universal remote control for AI agent frameworks. Connect any agent to a browser-based interface for real-time monitoring and remote interaction.

## Agent Support

| Agent | Status | Viewer → Agent | Agent → Viewer | How |
|-------|--------|----------------|----------------|-----|
| **Hermes Agent** | ✅ Supported | ✅ Messages | ✅ Tool calls, responses, status | Native plugin + `/remote-control` |
| DeepAgent | 🔜 Planned | — | — | `@axolotlai/arc-adapter-deepagent` |
| OpenClaw | 🔜 Planned | — | — | `@axolotlai/arc-adapter-openclaw` |
| Claude Code | 🔜 Planned | — | — | Skill file |

## Quick Start

```bash
# Install and configure
curl -fsSL https://raw.githubusercontent.com/axolotl-ai-cloud/arc/refs/heads/main/install.sh | sh
arc setup --hermes  # uses hosted beta relay — no server needed

# Start Hermes, then type /remote-control
hermes
```

The `/remote-control` skill starts a session, opens the viewer in your browser, and streams all tool calls and responses to the viewer in real-time.

> **Note:** `arc setup --hermes` patches the `hermes` entrypoint to enable
> bidirectional viewer ↔ agent messaging. If `hermes update` overwrites the
> patch, run `arc update` to re-apply it. Once
> [NousResearch/hermes-agent#3778](https://github.com/NousResearch/hermes-agent/pull/3778)
> is merged, the patch is unnecessary.

## How It Works

```
Agent (Hermes, DeepAgent, OpenClaw, any)
  │
  │  WebSocket
  ▼
Relay Server (arc-beta.axolotl.ai or self-hosted)
  │
  │  WebSocket
  ▼
Web Viewer (browser)
  • Live trace view (tool calls, messages, status)
  • Send messages to the agent
  • Approve/deny tool calls
```

Traces flow agent → relay → viewer. Commands flow viewer → relay → agent.

## Self-Hosted Relay

For users who want to run their own relay server:

```bash
# Option 1: Docker
docker compose up relay

# Option 2: Python directly
pip install -r relay/requirements.txt
python -m relay

# Option 3: Use the CLI (handles everything)
arc setup --self-hosted
```

### Environment Variables

```bash
# Required — set a fixed token, or one is auto-generated at startup
export AGENT_TOKEN="your-strong-random-token"

# Optional
export PORT=8600                        # Listen port (default: 8600)
export MAX_SESSIONS=100                 # Max concurrent sessions
export MAX_TRACE_LOG=2000               # Max trace events per session
export SESSION_TTL_HOURS=24             # Idle session cleanup
export ALLOWED_ORIGINS="*"              # CORS origins (comma-separated)
export REQUIRE_TLS=false                # Reject non-TLS connections
export AGENT_TOKEN_PREFIX=""            # Accept prefix-based tokens (beta mode)
```

### Running with `ARC_ENV=dev`

For local development, use `ARC_ENV=dev` to default to self-hosted mode:

```bash
# arc setup will default to localhost relay, auto-start it
ARC_ENV=dev arc setup --hermes

# Or start the relay manually
AGENT_TOKEN=dev-token python -m relay

# Then configure the CLI to use it
ARC_ENV=dev arc setup --self-hosted
```

### Verify the relay is running

```bash
curl http://localhost:8600/health
# {"status": "ok", "sessions": 0}
```

Open `http://localhost:8600/viewer` to access the web viewer (if web-client is built).

## Supported Frameworks

| Framework | Integration | How |
|-----------|-------------|-----|
| **Hermes Agent** | Native Python plugin | `/remote-control` or `arc_start_session` tool |
| **DeepAgent** (LangChain) | TypeScript middleware | `@axolotlai/arc-adapter-deepagent` |
| **OpenClaw** | TypeScript plugin | `@axolotlai/arc-adapter-openclaw` |
| **Claude Code** | Skill file | `/remote-control` slash command |
## CLI Commands

```bash
arc setup [--hermes|--self-hosted]  # Configure relay URL, token, framework
arc config [--viewer|--relay|...]   # Get or set individual config values
arc update                         # Pull, rebuild, reinstall skills
arc install-skill                  # Install /remote-control skill
arc status                         # Show current configuration
```

## Choosing a Viewer

By default, viewer links point to the viewer bundled into your relay server — the same built-in React app served at `/viewer` on whatever relay you're connected to. This is the simplest setup and requires no extra configuration.

There are two reasons you might want a different viewer URL:

**Use the OSS viewer on GitHub Pages** — useful if you want to verify the viewer source code independently of the relay operator. The viewer is deployed directly from this repo via GitHub Actions and can be inspected at any commit:
```bash
arc config --viewer https://axolotl-ai-cloud.github.io/arc
# When a session starts: https://axolotl-ai-cloud.github.io/arc?relay=https://arc-beta.axolotl.ai&session=...&s=...
```

**Use a locally running viewer** — useful when developing the web client or running fully air-gapped:
```bash
# In one terminal: start the dev viewer
npm run dev:viewer   # serves at http://localhost:5173

# In another terminal: point arc at it
arc config --viewer http://localhost:5173
# When a session starts: http://localhost:5173?relay=http://localhost:8600&session=...&s=...
```

Reset to the default relay-bundled viewer at any time:
```bash
arc config --viewer default
```

The viewer URL is stored in `~/.arc/config.json` and can also be set via environment variable:
```bash
ARC_VIEWER_BASE=https://axolotl-ai-cloud.github.io/arc
```

## Security Model

- **Agent token** — required to register sessions. Prevents unauthorized agents.
- **Session secret** — generated per-session, required for viewer subscription. Only share with trusted parties.
- **Role enforcement** — viewers can't send traces, agents can't send commands.
- **Rate limiting** — per-IP limits on HTTP (60/min) and WebSocket (120 msg/min).
- **TLS** — set `REQUIRE_TLS=true` in production.
- **Prefix tokens** — beta mode (`AGENT_TOKEN_PREFIX`) gives each agent its own session namespace.

## Extensibility

The relay is extensible via protocol interfaces:

```python
from relay import create_app, RelayConfig

app = create_app(RelayConfig(
    auth=MyAuthProvider(...),      # Authenticate agents, viewers, admins
    store=MySessionStore(...),     # Persist session state
    policy=MySessionPolicy(...),   # Enforce session limits
    hooks=MyLifecycleHooks(...),   # React to session events
))
```

## Project Structure

```
├── relay/                     # OSS relay server (Python/FastAPI)
├── packages/
│   ├── protocol/              # Wire types, client, crypto
│   ├── cli/                   # `arc` CLI (setup, connect, update)
│   ├── web-client/            # React SPA viewer
│   ├── adapter-hermes/        # Hermes Agent TypeScript adapter
│   ├── adapter-deepagent/     # DeepAgent adapter
│   └── adapter-openclaw/      # OpenClaw adapter
├── hermes-plugin/             # Native Hermes Python plugin
├── tests/                     # Integration tests
├── install.sh                 # curl | sh installer
└── docker-compose.yml         # Local dev
```

## Testing

```bash
npm run test:ts                # TypeScript tests
npm run test:py                # Python tests (needs pytest, pytest-asyncio, httpx)
npm test                       # All tests
```

## Roadmap

- [x] Per-session authentication
- [x] CLI with `arc setup` / `/remote-control`
- [x] Tool approval/deny from viewer
- [x] Native Hermes Agent plugin with lifecycle hooks
- [x] Beta relay with prefix-based tokens
- [x] Web viewer auto-connect from URL params
- [ ] Viewer → agent message injection (pending Hermes PR)
- [ ] Mobile app (iOS/iPadOS)
- [ ] Multi-agent dashboard view
- [ ] Persistent trace storage

## License

MIT. See [LICENSE](LICENSE).
