Documentation

Quick Start

Get Janus running locally and complete your first agent-to-agent task handoff in 5 minutes.

Prerequisites

• Docker & Docker Compose
• Python 3.10+ (for the SDK example)

1. Start Janus

The Compose file starts Janus server + PostgreSQL + NATS + Redis with a single command:

docker compose up -d

Verify all services are healthy:

curl -s http://localhost:8080/healthz
# → {"status":"ok"}

2. Install the Python SDK

pip install janus-sdk

3. Publish a Task

Create a file publish.py:

from janus_sdk import JanusClient

client = JanusClient("http://localhost:8080", tenant_id="acme")

# Create a mailbox for the reviewer agent
client.create_mailbox("review-mb", agent_id="reviewer")

# Publish a task to the mailbox
resp = client.publish_task({
    "id": "task-001",
    "source_agent": "product",
    "target_type": "mailbox",
    "target_value": "review-mb",
    "envelope": {
        "type": "code_review",
        "payload": {"pr_url": "https://github.com/org/repo/pull/42"},
        "priority": "high"
    }
})
print("Published:", resp.task_id)

python publish.py

4. Pull and Complete the Task

Create a file worker.py:

from janus_sdk import JanusClient

client = JanusClient("http://localhost:8080", tenant_id="acme")

# Pull task from mailbox
result = client.pull_task("review-mb", "reviewer")
print(f"Got task: {result.task.id}")

# Start processing (acquire lease)
client.start_task(result.task.id, result.lease.lease_id)

# Process... (in real code, do the work here)

# Acknowledge completion
client.ack_task(result.task.id, {
    "lease_id": result.lease.lease_id,
    "result_ref": "s3://review-result.json"
})
print("Task completed")

python worker.py

5. Verify via CLI

Use the Janus CLI to check task state:

janus task list --tenant acme
# → task-001  completed  2026-07-31T12:00:00Z

janus mailbox list --tenant acme
# → review-mb  tasks: 1  pending: 0

What's Next

• Read Core Concepts — understand mailboxes, tasks, leases, and envelopes
• SDK Guide — use Go, Python, or TypeScript SDKs
• Code Review Scenario — multi-agent code review pipeline