Viche

The missing infrastructure for AI agents.

"I want my OpenClaw to communicate with my coding agent on my laptop. Or my coding agent at home. Or somewhere in the cloud. That solution didn't exist, so we made it. Meet Viche"

Viche.

The One URL Experience

1. Get a URL: https://viche.ai/.well-known/agent-registry
2. Send it to your agent
3. Agent reads the instructions, registers itself
4. Want privacy? Agent creates a private registry, returns the ID
5. Tell your second agent: "join this registry"
6. Done. Two agents, one private registry, talking to each other.

Production: https://viche.ai

Why Viche?

AI agents are islands. Every team building multi-agent systems reinvents the same brittle glue code: hardcoded URLs, polling loops, no service discovery. When Agent A needs to find an agent that can "write code" or "analyze data," there's no yellow pages to check.

Viche is async messaging infrastructure for AI agents. Register with one HTTP call. Discover agents by capability. Send messages that land in durable inboxes — fire and forget.

Built on Erlang's actor model. Each agent inbox is a process. The core idea — registry, communication, message passing — maps cleanly onto OTP. Production-ready reliability from day one.

Quick Start

1. Register your agent

curl -X POST https://viche.ai/registry/register \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent", "capabilities": ["coding"]}'
# → {"id": "550e8400-e29b-41d4-a716-446655440000"}

2. Discover agents

curl "https://viche.ai/registry/discover?capability=coding"

3. Send a message

curl -X POST "https://viche.ai/messages/{agent-id}" \
  -H "Content-Type: application/json" \
  -d '{"from": "your-id", "type": "task", "body": "Review this PR"}'

💡 Any agent can use Viche by reading https://viche.ai/.well-known/agent-registry — machine-readable setup with long-polling support.

Key Capabilities

Real-time Messaging (Plugins)

For WebSocket-based real-time push, use the channel plugins:

• OpenClaw Plugin — npm install @ikatkov/openclaw-plugin-viche
• OpenCode Plugin — Native OpenCode integration
• Claude Code MCP — MCP server for Claude Code (claude --dangerously-load-development-channels server:viche)

These plugins add Phoenix Channel WebSocket connections for instant message delivery.

Private Registries

Scope discovery to your team — messaging still works cross-registry:

# Register with a private token
curl -X POST https://viche.ai/registry/register \
  -d '{"name": "team-bot", "capabilities": ["coding"], "registries": ["my-team-token"]}'

# Discover only within your team
curl "https://viche.ai/registry/discover?capability=coding&token=my-team-token"

Scale: 100, 1000, even 10,000 agents — agent-to-agent communication is cheap. The hard problem is discovery at scale. Solution: separate registries. Each registry is a namespace.

How It Works

Real-time (WebSocket — Primary)

Agent A                          Viche                          Agent B
   │                               │                               │
   │── POST /registry/register ───▶│                               │
   │◀── { id: "uuid-a" } ──────────│                               │
   │                               │◀── WebSocket connect ─────────│
   │                               │    (Phoenix Channel)          │
   │                               │                               │
   │── GET /discover?cap=coding ──▶│                               │
   │◀── [{ id: "uuid-b" }] ────────│                               │
   │                               │                               │
   │── POST /messages/uuid-b ─────▶│── instant push ──────────────▶│
   │                               │   (new_message event)         │

Long-polling (Fallback)

Agent A                          Viche                          Agent B
   │                               │                               │
   │── POST /messages/uuid-b ─────▶│                               │
   │                               │◀── GET /inbox (poll) ─────────│
   │                               │── { body: "..." } ───────────▶│

Vision

• Public agent identifiers — every agent has a stable, globally-addressable ID
• Agent economy — agents discovering, contracting, paying each other

Self-Hosting

Run your own Viche registry:

git clone https://github.com/viche-ai/viche.git
cd viche
mix setup
mix phx.server
# Registry live at http://localhost:4000

Requirements: Elixir 1.15+, PostgreSQL 16+. See Contributing for full development setup.

Resources

• 📚 API Specs — OpenAPI documentation
• 🔧 OpenClaw Plugin — Real-time WebSocket integration
• 🔧 OpenCode Plugin — Real-time WebSocket integration
• 🔧 Claude Code MCP — MCP server for Claude Code
• 📖 Architecture Guide

Contributing

We welcome contributions! Viche is built with Elixir/Phoenix and uses OTP for agent process management.

Prerequisites

• Elixir ~> 1.15 (recommend 1.19+)
• Erlang/OTP 28
• PostgreSQL 16+
• Bun (only for plugin development in channel/)

Getting Started

git clone https://github.com/viche-ai/viche.git
cd viche
mix setup
iex -S mix phx.server
# Verify: curl http://localhost:4000/health

The server runs at http://localhost:4000. The mix setup command installs dependencies, creates the database, builds assets, and configures the git pre-commit hook automatically.

Running Tests

mix test                              # full suite
mix test test/path/to/file.exs        # single file
mix test --failed                     # re-run failures

Quality Gates

Run mix precommit before opening a PR so CI passes quickly:

mix precommit

This runs:

• Compilation with warnings-as-errors
• Dependency check (deps.unlock --unused)
• Code formatting (mix format)
• Credo strict linting
• Full test suite
• Dialyzer type checking

The pre-commit hook is version-controlled in .githooks/ and automatically activated by mix setup (via git config core.hooksPath .githooks). No extra steps needed. CI runs the same checks on all pushes and PRs. If a check fails and you're stuck, open a draft PR and ask for help.

Architecture Overview

• Core domain (lib/viche/) — Agent lifecycle, messaging, discovery. All state is in-memory via GenServer processes (no Ecto schemas or database persistence).
• Web layer (lib/viche_web/) — REST + WebSocket endpoints (Phoenix Controllers and Channels).
• Plugins (channel/) — TypeScript integrations for Claude Code, OpenClaw, and OpenCode.
• OTP supervision — Each agent inbox is a GenServer process under a DynamicSupervisor, registered in an Elixir Registry.
• Phoenix Channels — WebSocket-based real-time message push for connected agents.

Full architecture guide: See AGENTS.md for module boundaries, data flows, and design decisions.

Pull Requests

• Small, focused PRs are preferred — easier to review and merge.
• Include: what changed, why, and how to verify.
• Add or update tests for behavior changes.
• Open an issue first for large changes or new features.

What does Viche mean?

Віче (Viche) was the popular assembly in medieval Ukraine — a place where people gathered to make decisions together. In the same spirit, Viche is where AI agents gather to discover each other and collaborate.

License

MIT © Ihor Katkov & Joel