queuekit

Agentic-first message queue service. Enqueue, dequeue, and process messages with visibility timeouts, retries, and dead letter queues. Plain text API, agent-driven, single Go binary with JSON file storage.

Why?

AI agents need async task coordination. Queuekit gives agents a simple HTTP message queue — enqueue work, dequeue and process it, handle failures with retries and dead letter queues. No SDK, no UI, just plain text over HTTP.

Quick Start

# Build and run
make build
./queuekit

# Or with Go directly
go run ./cmd/queuekit

# It listens on :7199 by default

Auth Flow

# 1. Create a workspace
curl -X POST localhost:7199/workspaces -d '{"name":"myteam"}'
# → handle=ws_abc12 name=myteam plan=free created=...

# 2. Request OTP (code is logged to stderr in dev mode)
curl -X POST localhost:7199/auth/request -d '{"email":"you@example.com","workspace":"ws_abc12"}'
# → ok: OTP sent | code=123456 | hint: ...

# 3. Verify OTP to get bearer token
curl -X POST localhost:7199/auth/verify -d '{"email":"you@example.com","code":"123456"}'
# → token=abc123... workspace=ws_abc12

Using the Queue

# Create a queue
curl -H "Authorization: Bearer <token>" \
  -X POST localhost:7199/queues \
  -d '{"name":"tasks","visibility_timeout":30,"max_retries":3}'

# Enqueue a message
curl -H "Authorization: Bearer <token>" \
  -X POST localhost:7199/messages/queue_x1y2z/enqueue \
  -d '{"body":"process order #1234"}'

# Dequeue the next message (leases it for visibility_timeout seconds)
curl -H "Authorization: Bearer <token>" \
  -X POST localhost:7199/messages/queue_x1y2z/dequeue

# Acknowledge (complete) the message
curl -H "Authorization: Bearer <token>" \
  -X POST localhost:7199/messages/msg_abc12/ack

# Negative acknowledge (retry or dead-letter after max_retries)
curl -H "Authorization: Bearer <token>" \
  -X POST localhost:7199/messages/msg_abc12/nack

# Check queue stats
curl -H "Authorization: Bearer <token>" \
  localhost:7199/queues/queue_x1y2z/stats

# List messages by status
curl -H "Authorization: Bearer <token>" \
  localhost:7199/messages/queue_x1y2z?status=pending

Dead Letter Queues

When a message exceeds max_retries, it's either marked as dead or moved to a dead letter queue (DLQ) if one is configured:

# Create a DLQ
curl -H "Authorization: Bearer <token>" \
  -X POST localhost:7199/queues \
  -d '{"name":"failed-tasks"}'

# Create a main queue with DLQ
curl -H "Authorization: Bearer <token>" \
  -X POST localhost:7199/queues \
  -d '{"name":"tasks","max_retries":3,"dead_letter_queue":"queue_dlq12"}'

API Reference

Method	Path	Description
GET	/help	Operating manual for agents
POST	/auth/request	Request OTP (email + workspace)
POST	/auth/verify	Verify OTP → bearer token
GET	/workspaces	List workspaces
POST	/workspaces	Create workspace
GET	/queues	List queues
POST	/queues	Create queue
GET	/queues/{handle}	Get queue details
PATCH	/queues/{handle}	Update queue settings
DELETE	/queues/{handle}	Delete queue + messages
POST	/queues/{handle}/purge	Remove all messages
GET	/queues/{handle}/stats	Queue statistics
POST	/messages/{queue}/enqueue	Enqueue a message
POST	/messages/{queue}/dequeue	Dequeue next message
POST	/messages/{msg}/ack	Acknowledge message
POST	/messages/{msg}/nack	Negative acknowledge
GET	/messages/{queue}	List messages (?status=pending)
GET	/messages/{queue}/{msg}	Get message details
DELETE	/messages/{queue}/{msg}	Delete a message
GET	/audit	Audit log (?limit=20)
POST	/mcp	MCP JSON-RPC 2.0 endpoint

Response Format

Plain text by default — one record per line, key=value pairs:

handle=queue_a1b2c name=tasks visibility_timeout=30s max_retries=3 enqueued=42 dequeued=40 acked=38 dead=0

Add Accept: application/json or ?format=json for JSON responses.

Errors include hints:

error: queue not found | hint: list queues with GET /queues to find valid handles

Configuration

Flag	Env Var	Default	Description
-addr	QUEUEKIT_ADDR	:7199	Listen address
-data	QUEUEKIT_DATA	./data	Data directory
-secret	QUEUEKIT_SECRET	(auto)	Token signing secret
-smtp-url	QUEUEKIT_SMTP_URL	(empty)	SMTP server URL
-smtp-from	QUEUEKIT_SMTP_FROM	queuekit@localhost	OTP email from address

MCP Integration

Queuekit speaks Model Context Protocol at /mcp for direct integration with Claude, Cursor, and other MCP-aware clients. Available tools: list_queues, create_queue, enqueue, dequeue, ack, nack, queue_stats.

Build

make build    # CGO_ENABLED=0, single binary
make test     # go test -race
make vet      # go vet

License

MIT