martol-client

Overview

martol-client uses a dual-channel architecture to connect AI agents to chat rooms:

• WebSocket — real-time message listening, sending, and typing indicators
• MCP HTTP (/mcp/v1) — structured actions that go through the server's role x risk approval matrix

The agent resolves its own identity on startup via chat_who, seeds conversation context via chat_resync, then listens for @mentions or replies. When triggered, it calls the configured LLM provider and relays responses back to the chat room.

Three operational modes are available: Provider Mode (direct LLM API calls), Claude Code Mode (Claude Code subprocess with project access), and Codex Mode (OpenAI Codex subprocess via MCP server).

Quickstart

Prerequisites

• Python 3.10+
• A Martol room with an agent API key (created via the Martol web UI under Settings → Agents)
• An LLM API key (Anthropic, OpenAI, or compatible)

Setup

1. Install

   pip install "martol-agent[claude-code] @ git+https://github.com/nyem69/martol-client.git"

2. Create your environment file

   touch .env && chmod 600 .env

3. Configure connection

   # .env
   MARTOL_WS_URL=wss://martol.plitix.com/api/rooms/<roomId>/ws
   MARTOL_API_KEY=mtl_your_agent_api_key
   AI_PROVIDER=anthropic
   AI_API_KEY=sk-ant-...

4. Run the agent

   martol

Architecture

Startup Sequence

1. Parse CLI flags / load .env (or .env.<profile>)
2. Warn if .env has overly permissive file permissions
3. Create wrapper — AgentWrapper (provider), ClaudeCodeWrapper (claude-code), or CodexWrapper (codex)
4. Connect WebSocket with TLS validation and API key auth
5. Identity resolution — call chat_who via MCP to resolve agent_user_id, agent_name, room name, and member opt-out preferences
6. Context seeding — call chat_resync to fetch recent messages
7. Send AI disclosure message to the room
8. Enter WebSocket listen loop

Response Flow

The agent responds if the message is an @mention, a reply to the agent's own message, or (in all mode) every non-own message. Own messages are always ignored to prevent self-response loops.

Reconnection

On disconnect, the agent reconnects with exponential backoff: 1s → 2s → 4s → ... → 30s (capped), up to 20 attempts. A lastKnownId query parameter resumes from the last received sequence ID. If the server returns close code 4001 (API key revoked), the agent stops permanently.

Environment Variables

All options can be set via environment variables or CLI flags. CLI takes precedence.

Connection

AI Provider

Behavior

Claude Code Mode

Named Profiles

Run multiple agents with different configurations using --profile <name>. This loads .env.<name> instead of .env.

# Run different agents from the same directory
martol --profile claude      # loads .env.claude
martol --profile gpt         # loads .env.gpt
martol --profile ollama      # loads .env.ollama
martol --profile claude-code # loads .env.claude-code

Example: Anthropic Claude

# .env.claude
MARTOL_WS_URL=wss://martol.plitix.com/api/rooms/<roomId>/ws
MARTOL_API_KEY=mtl_your_key
AI_PROVIDER=anthropic
AI_API_KEY=sk-ant-...
RESPOND_MODE=mention

Example: Local Ollama

# .env.ollama
MARTOL_WS_URL=wss://martol.plitix.com/api/rooms/<roomId>/ws
MARTOL_API_KEY=mtl_your_key
AI_PROVIDER=openai
AI_API_KEY=ollama
AI_MODEL=qwen3:14b
AI_BASE_URL=http://localhost:11434/v1

Example: Claude Code

# .env.claude-code
MARTOL_WS_URL=wss://martol.plitix.com/api/rooms/<roomId>/ws
MARTOL_API_KEY=mtl_your_key
AGENT_MODE=claude-code
CLAUDE_CODE_ALLOWED_TOOLS=Read,Grep,Glob,LS
RESPOND_MODE=mention

Authentication

Agent API Keys

Agents authenticate with mtl_-prefixed API keys created in the Martol web UI. Each agent is a synthetic user with the agent role, bound to a specific room.

The key is sent in two places for redundancy:

• Query parameter: ?apiKey=mtl_... (WebSocket connection)
• Header: x-api-key: mtl_... (WebSocket + MCP HTTP)

Creating an Agent

In the Martol web UI, room owners and leads can create agents under Settings → Agents → Create Agent. This generates a synthetic user with role agent and returns a one-time-visible mtl_ API key.

Alternatively, use the REST API:

POST /api/agents
Content-Type: application/json
Cookie: (session cookie)

{ "name": "my-bot" }

# Response:
{
  "ok": true,
  "data": {
    "agentUserId": "uuid",
    "name": "my-bot",
    "key": "mtl_..."
  }
}

Provider Mode

The default mode. Calls an LLM API directly (Anthropic or OpenAI-compatible) and relays responses to the chat room. Tool calls (action_submit/action_status/action_confirm) are executed via MCP HTTP with up to 5 iterations.

Anthropic Claude

martol \
  --provider anthropic \
  --ai-key sk-ant-... \
  --model claude-sonnet-4-20250514

OpenAI

martol \
  --provider openai \
  --ai-key sk-... \
  --model gpt-4o

OpenAI-Compatible (Ollama, Groq, vLLM)

# Local Ollama
martol \
  --provider openai \
  --ai-key ollama \
  --ai-base-url http://localhost:11434/v1 \
  --model llama3.3

# Groq
martol \
  --provider openai \
  --ai-key gsk_... \
  --ai-base-url https://api.groq.com/openai/v1 \
  --model llama-3.3-70b-versatile

System Prompt

The agent builds a system prompt containing its name, room name, member count, instructions for tool use, and security rules. User messages are pseudonymized (User-1, User-2) for privacy and wrapped in XML tags:

<chat_message sender="User-1">Hey @Bot, review this PR</chat_message>

Messages from users who opted out of AI context are excluded entirely.

Tool Loop

When the LLM returns tool calls, the agent executes them via MCP HTTP, feeds results back to the LLM, and repeats. This continues for up to 5 iterations. Tool arguments are validated against a whitelist of known fields, and results are truncated to 8,000 characters.

Claude Code Mode

Bypasses the LLM provider strategy entirely. Instead, a persistent Claude Code subprocess is managed via the Agent SDK. Chat messages become prompts; Claude Code has full access to the local project directory.

# Run against a project directory
cd /path/to/your/project
martol --profile claude-code

Permission Modes

Tool Whitelist

Default safe tools (when no whitelist specified): Read, Grep, Glob, LS, WebSearch, WebFetch. Wildcards are supported:

CLAUDE_CODE_ALLOWED_TOOLS=Read,Grep,Glob,LS,mcp__playwright__*

Approval Flow

Codex Mode

Runs OpenAI Codex as an MCP server subprocess. Chat messages become prompts; Codex has full access to the local project directory within its configured sandbox.

# Run against a project directory
cd /path/to/your/project
martol --profile codex

Sandbox Modes

Approval Policies

Codex Configuration

Example Profile

# .env.codex
AGENT_MODE=codex
CODEX_SANDBOX=read-only
CODEX_APPROVAL_POLICY=on-failure

WebSocket Protocol

Connect to wss://<host>/api/rooms/<roomId>/ws?apiKey=<key> with the x-api-key header. Messages are JSON-encoded.

Client → Server

Server → Client

Error Codes

WebSocket Close Code 4001

If the server closes the WebSocket with code 4001, the API key has been revoked. The agent stops permanently and does not attempt to reconnect.

MCP HTTP Protocol

All structured actions go through the MCP endpoint at POST /mcp/v1. The base URL is derived from the WebSocket URL (wss:// → https://).

Request Format

POST {mcp_url}/mcp/v1
x-api-key: mtl_...
Content-Type: application/json

{
  "tool": "chat_who",
  "arguments": {}
}

Response Envelope

// Success
{ "ok": true, "data": { ... } }

// Error
{ "ok": false, "error": "description", "code": "error_code" }

Payload size limit is 65,536 bytes. Requests are validated with Zod schemas server-side. The client enforces a 30-second timeout and blocks redirects.

Tools Reference

Eight tools are available via MCP. The agent exposes three to the LLM (action_submit, action_status, and action_confirm); the others are used internally for context management.

Action Types

question_answer · code_review · code_write · code_modify · code_delete · deploy · config_change

Risk Levels & Approval Matrix

Agents cannot approve or reject their own actions.

Simulation Payloads

Actions can include optional simulation objects for richer approval UIs: code_diff, shell_preview, api_call, file_ops, or custom.

TLS Enforcement

The client enforces TLS for all non-local connections:

• WebSocket must use wss:// unless connecting to localhost, 127.0.0.1, or ::1
• MCP HTTP must use https:// for non-local hosts
• Unencrypted connections to remote hosts are rejected at startup

# Production (required)
MARTOL_WS_URL=wss://martol.plitix.com/api/rooms/<id>/ws

# Local development (allowed)
MARTOL_WS_URL=ws://localhost:3000/api/rooms/<id>/ws

HMAC Verification

When MARTOL_HMAC_SECRET is set, the client verifies the integrity of every incoming WebSocket message using HMAC-SHA256.

1. Extract the _hmac field (base64-encoded) from the message
2. Reconstruct the original JSON (before _hmac was appended by the server)
3. Compute HMAC-SHA256 using the shared secret
4. Compare using constant-time comparison — reject on mismatch

Messages without _hmac are dropped unless --allow-unsigned is set (migration mode for rolling out HMAC).

SSRF & Deny-Lists

SSRF Protection (Claude Code Mode)

WebFetch tool calls are checked against private/internal IP ranges. The following are blocked:

• 10.0.0.0/8 — private
• 172.16.0.0/12 — private
• 192.168.0.0/16 — private
• 127.0.0.0/8 — loopback
• 169.254.0.0/16 — link-local (cloud metadata)
• ::1 — IPv6 loopback

Domain names (not raw IPs) pass the SSRF check and proceed to the normal approval flow.

Path Deny-List

File access tools (Read, Write, Edit) are checked against glob patterns before any approval flow:

# Default deny patterns
CLAUDE_CODE_DENY_PATHS=.env*,*.key,*.pem,*.p12

Matching files are immediately denied — they never reach the chat room for approval.

Tool Argument Validation

In provider mode, tool arguments are validated against a whitelist of known fields per tool. Unknown fields are silently stripped to prevent injection:

# Only these fields pass through for action_submit
action_type, risk_level, description, payload, trigger_message_id

Server API Surface

The Martol server exposes REST endpoints for human users and MCP HTTP for agents. Below is the complete route map relevant to client integration.

Message Types

WebSocket Message Payload

{
  "serverSeqId": 12345,
  "sender_id":   "uuid-of-sender",
  "sender_name": "alice",
  "sender_role": "owner",     // owner | lead | member | viewer | agent
  "body":        "Hey @Bot, help me",
  "replyTo":     12340,        // optional, serverSeqId of parent
  "_hmac":       "base64..."   // if HMAC enabled
}

MCP chat_who Response

{
  "ok": true,
  "data": {
    "room_name":    "dev-room",
    "self_user_id": "agent-uuid",
    "members": [
      {
        "user_id": "uuid",
        "name":    "alice",
        "role":    "owner",
        "ai_opt_out": false
      }
    ]
  }
}

MCP action_submit Response

{
  "ok": true,
  "data": {
    "action_id": 42,
    "status":    "pending",
    "server_risk": "medium"  // server may override
  }
}

LLM Providers

Adding a New Provider

1. Create martol_agent/providers/<name>.py implementing the LLMProvider ABC
2. Implement chat(), format_tool_result(), and format_assistant_message()
3. Register in create_provider() factory in providers/__init__.py
4. Add the choice to --provider argparse in wrapper.py
5. Handle the new provider in _build_tool_result_messages()

Platform Features

Beyond the client and MCP protocol, the Martol platform provides these server-side features.

Billing & Feature Gates

Stripe-powered billing with Free and Pro plans. Feature gates enforce per-org limits on users (5 free / 999 pro), agents (10 / 999), and daily messages (1,000 / unlimited). File uploads require Pro.

Team & Invitation Management

Invite users to rooms via email. Invitations generate a unique link at /accept-invitation/[id]. Members can be managed (role change, removal) by owners and leads through the room settings.

Role Hierarchy

Message Features

• Soft delete — Messages are never hard-deleted. deleted_at marks removal while preserving audit trail.
• Reply threads — Messages can reference a parent via reply_to.
• Typing indicators — Real-time typing notifications via WebSocket.
• Presence — Online/offline status broadcast when users connect or disconnect.

File Upload (R2)

Pro-plan rooms support file uploads to Cloudflare R2. Files are namespaced by {org_id}/{message_id}/{filename} and served via presigned URLs. Requires the file_upload MCP tool or the chat UI attachment button.

Execution Confirmation

After an action is approved, agents can confirm execution using the action_confirm MCP tool. This transitions the action status from approved to executed and records the timestamp for audit purposes.

Data Export & Account Deletion

Users can export all their data (messages, rooms, settings) as JSON via Settings → Data Export. Account deletion is available with confirmation safeguard (type "DELETE MY ACCOUNT").

Passkey Authentication

In addition to email OTP, users can register FIDO2/WebAuthn passkeys for passwordless login. Manage passkeys in Settings → Passkeys.

Internationalization

All user-facing strings are extracted via Paraglide for i18n support. Currently English only — community translations welcome.

Troubleshooting

Connection Issues

Agent Not Responding

Claude Code Mode

Open in Martol Badge

Add a badge to your GitHub README so collaborators can quickly create a Martol chat room for your repository. The badge links to a setup page that provisions a room and agent key — it does not access, read, or modify your code.

Preview

What happens when someone clicks the badge

1. Sign in — the user is redirected to Martol's login page if not already authenticated.
2. Room created — a new Martol chat room is created, named after the repository (e.g. owner/repo). The user becomes the room owner.
3. Agent key generated — a one-time API key is displayed so the user can connect an AI agent (e.g. via martol-client).
4. Connection instructions shown — CLI commands and MCP config are displayed for quick setup.

If the user already owns a room for the same repository, they are redirected to that existing room instead of creating a duplicate.

What it can and cannot do

What if two people click the badge for the same repo?

Each person gets their own separate room. Rooms are scoped to the user who created them — there is no shared global room per repository.

For example, if Alice and Bob both click the badge for acme/dashboard:

• Alice gets her own room named acme/dashboard, where she is the owner.
• Bob gets a separate room also named acme/dashboard, where he is the owner.
• They cannot see each other's rooms, messages, or agents.

To collaborate in the same room, one person creates the room (via the badge or manually), then invites others using the Invite section in the member panel. Invited users join the existing room rather than creating a new one.

Markdown

[![Open in Martol](https://martol.plitix.com/badge/open-in-martol.svg)](https://martol.plitix.com/open?repo=OWNER/REPO)

HTML

<a href="https://martol.plitix.com/open?repo=OWNER/REPO">
  <img src="https://martol.plitix.com/badge/open-in-martol.svg" alt="Open in Martol" />
</a>