S0RA Agent

Hermes-aligned CLI and plugins for real-time voice bridges.

One companion layer. Multiple voice providers. No isolation fantasy.

Website · Install · Quick Start · Architecture · Bridge Elements · Release Readiness

What this release is

S0RA Agent is a voice companion layer for Hermes-style agents. It keeps the useful CLI and plugin pieces for real-time voice, MCP, and VOIP control without pretending to be a separate isolated chat assistant.

This release ships a working CLI (sora), a FastAPI dashboard, a Hermes plugin (sora-hermes), a VOIP plugin (sora-voip), and scaffolding for seven voice providers. The live Discord voice bridge is not spawned by this repo alone — it is provided by the separate Hermes discord-voice plugin, which S0RA can configure, query, and extend.

Relationship to the Gemini bridge: S0RA shares the same bridge-element philosophy as gemini-live-discord-bridge — operator-facing tools, a sidecar health surface, status truth-tagging, and a public docs/site. It is a separate product/runtime: Gemini bridge is a single Discord voice bridge; S0RA is a multi-provider companion CLI and plugin registry.

Status map

Area	Status	Truthful scope
CLI entry (`sora --help`, `sora status`, `sora doctor`)	WORKING	Verified commands. 17 pytest tests pass.
Setup wizard (`sora setup`)	WORKING	Interactive provider/API-key configuration.
Provider registry (`sora voice providers`)	WORKING	List/enable/disable TTS/STT/LLM-voice providers.
ElevenLabs signed URLs / WebSocket targets	WORKING	URL generation and bridge prep implemented.
FastAPI dashboard (`/health`, `/api/status`)	WORKING	Default port `8080`. Verified with `TestClient`.
Hermes plugin (`sora-hermes`)	WORKING	Registers `sora_voice_` and `sora_mcp_` tools.
Discord voice bridges (`sora voice live/vapi/…`)	PARTIAL	CLI validates config and prepares bridge args. Live bridging requires the Hermes `discord-voice` plugin runtime.
MCP server management	PARTIAL	Start/status/catalog CLI works; WebSocket/SSE paths are scaffolding.
VOIP Asterisk + Dograh bridge (`sora-voip`)	PARTIAL	Plugin and ARI/SIP commands exist. Needs Asterisk/Dograh runtime.
TUI mode (`sora tui`)	PLANNED	Stub falls back to REPL. Not a real Ink/React TUI yet.
Interactive cron creation (`sora cron`)	PLANNED	List/show works; create/run are stubs.
Skill search/browse/audit (`sora skills`)	PLANNED	Commands exist but operations are not implemented.
Session log filtering (`sora logs`)	PLANNED	View works; filtering is not implemented.
Doctor auto-fix (`sora doctor --fix`)	PLANNED	Diagnostics work; auto-fix is a stub.
ACP adapter (`sora acp`)	RESEARCH	Entry point stub; no full ACP server implementation.

See docs/release-readiness.md for the full truth table, hard release rules, and E2E smoke checklist.

Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│  User surface: sora CLI  │  FastAPI dashboard  │  Hermes chat (via plugin)   │
└──────────────────────────┴─────────────────────┴───────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                       S0RA CLI / API layer                                  │
│  setup · voice · mcp · status · doctor · config · plugins · skills · cron │
└───────────────────────────────┬─────────────────────────────────────────────┘
                                │
        ┌───────────────────────┼───────────────────────┐
        ▼                       ▼                       ▼
┌───────────────┐      ┌───────────────┐      ┌───────────────────────┐
│ sora-hermes   │      │ sora-voip     │      │ built-in runtime      │
│ plugin        │      │ plugin        │      │ (MCP scaffolds,       │
│               │      │               │      │  provider registry,   │
│ Registers     │      │ Asterisk ARI  │      │  FastAPI dashboard)   │
│ sora_voice_*  │      │ + Dograh      │      │                       │
│ tools in      │      │ SIP/RTP       │      │                       │
│ Hermes        │      │               │      │                       │
└───────┬───────┘      └───────┬───────┘      └───────────┬───────────┘
        │                      │                          │
        ▼                      ▼                          ▼
┌───────────────┐      ┌───────────────┐      ┌───────────────────────┐
│ Hermes        │      │ Asterisk      │      │ Provider backends     │
│ discord-voice │      │ PBX + Dograh  │      │ (Gemini, Vapi,       │
│ plugin        │      │ gateway       │      │ ElevenLabs, OpenAI,   │
│               │      │               │      │ xAI, Ultravox, Retell)│
│ Live bridge   │      │ Phone bridge  │      │                       │
│ runtime       │      │ runtime       │      │                       │
└───────────────┘      └───────────────┘      └───────────────────────┘

Read the full design in docs/guide/architecture.md.

Quick start

# 1. Install
pipx install git+https://github.com/Capslockb/sora-agent
# or: git clone ... && pip install -e .

# 2. Run the setup wizard
sora setup

# 3. Verify the install
sora --version
sora doctor
sora status

# 4. Check provider state
sora voice providers list

# 5. Start the dashboard (optional)
sora dashboard start --port 8080
# Open http://127.0.0.1:8080/health

Verification commands

sora --help
sora status --json
sora voice status
sora mcp status
python -m pytest tests/ -q

See docs/guide/quick-start.md for install pitfalls and next steps.

S0RA bridge elements

S0RA exposes a small operator-friendly tool surface. When the sora-hermes plugin is enabled, these tools register in Hermes:

Tool	Status	What it does
`sora_voice_live`	PARTIAL	Prepare/start Gemini Live Discord bridge args. Runtime provided by Hermes `discord-voice`.
`sora_voice_vapi`	PARTIAL	Prepare/start Vapi Discord bridge args. Runtime provided by Hermes `discord-voice`.
`sora_voice_leave`	PARTIAL	Stop active voice bridge via Hermes `discord-voice`.
`sora_voice_status`	WORKING	Return structured voice bridge status from S0RA state.
`sora_mcp_start`	PARTIAL	Start MCP server (stdio supported; HTTP/SSE scaffolding).
`sora_mcp_status`	WORKING	Return MCP server status.

Read the deep doc in docs/bridge-elements.md.

Feature matrix

Feature	Status	Doc	Caveat
CLI help/version/status/doctor	WORKING	`reference/cli/sora.md`	—
Setup wizard	WORKING	`reference/cli/setup.md`	—
Provider enable/disable	WORKING	`guide/voice/providers.md`	—
ElevenLabs URL signing	WORKING	`guide/voice/elevenlabs.md`	—
FastAPI dashboard	WORKING	`reference/cli/dashboard.md`	Default port `8080`.
Hermes plugin tools	WORKING	`reference/plugins/sora-hermes.md`	Requires `discord-voice` for live audio.
Discord voice bridges	PARTIAL	`guide/voice/gemini-live.md`	Live runtime in Hermes `discord-voice`.
VOIP Asterisk/Dograh	PARTIAL	`voip/setup.md`	Needs PBX runtime.
MCP server	PARTIAL	`guide/mcp/servers.md`	stdio works; WS/HTTP scaffolding.
TUI	PLANNED	`reference/cli/tui.md`	Stub only.
Cron	PLANNED	`reference/cli/cron.md`	Partial.
Skills	PLANNED	`reference/cli/skills.md`	Partial.
Logs	PLANNED	`reference/cli/logs.md`	Partial.
Doctor auto-fix	PLANNED	`reference/cli/doctor.md`	Partial.
ACP adapter	RESEARCH	`reference/cli/acp.md`	Stub only.

Required environment

The three critical pieces of configuration:

# ~/.sora/.env
GEMINI_API_KEY=...            # For Gemini Live bridge
DISCORD_BOT_TOKEN=...         # For Discord voice bridges (Hermes discord-voice)
ELEVENLABS_API_KEY=...        # Optional, for ElevenLabs bridge

See docs/env-vars.md for the exhaustive grouped reference.

Sidecar HTTP control API

The S0RA dashboard exposes local control endpoints on the configured port (default 8080):

Method	Path	Description	Status
GET	`/health`	API liveness	WORKING
GET	`/api/status`	Voice/MCP/VOIP/system status	WORKING
GET	`/api/visualizer/state`	UI-friendly visualizer snapshot	WORKING
GET	`/api/dashboard/stats`	CPU/memory metrics	WORKING
POST	`/api/voice/start`	Prepare voice bridge start	PARTIAL
POST	`/api/mcp/start`	Start MCP server	PARTIAL

Full route list in docs/bridge-elements.md.

What this repo does not currently ship

To prevent over-promising:

A standalone live Discord voice bridge. The audio path lives in the Hermes discord-voice plugin. S0RA configures and queries it.
A hosted phone service. VOIP requires your own Asterisk PBX and Dograh gateway.
A cloud transcription API. S0RA can point at external Whisper endpoints, but does not host one.
A finished TUI. sora tui is a stub.
A finished ACP server. sora acp is a research stub.
Auto-fix diagnostics. sora doctor --fix is not implemented.

Release verification checklist

# 1. CLI sanity
sora --help
sora --version

# 2. Health checks
sora doctor
sora status
sora voice status
sora mcp status

# 3. API health
curl -s http://127.0.0.1:8080/health | python3 -m json.tool

# 4. Test suite
python -m pytest tests/ -q

# 5. Hermes plugin registration (when Hermes is installed)
hermes plugins enable sora-hermes
hermes tools list | grep sora_

Expected results: CLI returns 0, doctor reports no hard failures, API returns {"status":"healthy"}, tests pass.

Documentation

docs/guide/quick-start.md — install, first commands, pitfalls
docs/guide/architecture.md — system map, audio path, integration boundaries
docs/bridge-elements.md — operator tools, sidecar API, wiring
docs/env-vars.md — exhaustive env var reference
docs/release-readiness.md — status legend, truth table, release blockers
docs/troubleshooting.md — common failures and log locations
docs/.vitepress/config.mts — VitePress docs-site nav

License

MIT — see LICENSE.

Name		Name	Last commit message	Last commit date
Latest commit History 44 Commits
.github/workflows		.github/workflows
__pycache__		__pycache__
acp_adapter		acp_adapter
docs		docs
optional-mcps		optional-mcps
plugins		plugins
sora_agent.egg-info		sora_agent.egg-info
sora_cli		sora_cli
tests		tests
ui-tui		ui-tui
vendor/pupuplatter-reference		vendor/pupuplatter-reference
website		website
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml
sora_api.py		sora_api.py
sora_bootstrap.py		sora_bootstrap.py
sora_constants.py		sora_constants.py
sora_logging.py		sora_logging.py
sora_mcp.py		sora_mcp.py

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

S0RA Agent

Hermes-aligned CLI and plugins for real-time voice bridges.

What this release is

Status map

Architecture

Quick start

Verification commands

S0RA bridge elements

Feature matrix

Required environment

Sidecar HTTP control API

What this repo does not currently ship

Release verification checklist

Documentation

License

About

Uh oh!

Releases 1

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

S0RA Agent

Hermes-aligned CLI and plugins for real-time voice bridges.

What this release is

Status map

Architecture

Quick start

Verification commands

S0RA bridge elements

Feature matrix

Required environment

Sidecar HTTP control API

What this repo does not currently ship

Release verification checklist

Documentation

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages