GitHub - dsecurity49/Intent-Bus: POST a job → any script can pick it up and execute it. A dead-simple distributed job bus for bots and scripts.

Run code on any device from anywhere — using just HTTP.
Intent Bus is a zero-infrastructure job coordination system with retries, atomic locking, priority scheduling, and cross-device workers.
Built for developers who want something lighter than Redis, RabbitMQ, or Firebase, while still being more reliable than cron.

•Why I built this •Cross-device automation guide

What makes this different?

• Trigger your Android phone from a cloud server
• Run jobs across devices without opening ports
• Coordinate scripts using just HTTP + curl
• Priority queues so important jobs are claimed first
• Capability routing so workers only claim supported jobs
• Dead-letter queue so failed jobs are archived instead of disappearing
• No Redis, RabbitMQ, or managed broker required

No external broker. Just a minimal Flask + SQLite core.

How it works

1. A client POSTs a job to /intent
2. Workers poll /claim
3. One worker atomically claims the job
4. Worker executes and calls /fulfill/<id>
5. Failed jobs are retried with exponential backoff
6. Jobs exceeding retry limits move to the dead-letter queue

Claims are lease-based and automatically expire if a worker disappears before fulfillment.

graph LR
    A[Cloud Script] -->|POST /intent| B[Intent Bus]
    B -->|claim + fulfill| C[Worker]
    C -->|execute task| D[Phone / System Action]

Why not just use X?

Who is this for?

• Developers running scripts across multiple machines
• People using Termux / Android automation
• Indie hackers avoiding infrastructure complexity
• Anyone wanting job queues without Redis or RabbitMQ

Intent Bus is designed for low-to-medium traffic workloads and performs well under moderate concurrency when deployed with Docker.

Authentication

Intent Bus supports two auth modes for regular clients and a separate admin auth layer.

Standard Auth

Works with curl, bash scripts, and lightweight devices.

Strict Auth

Strict auth supports:

• HMAC-SHA256 signed requests
• Nonce-based replay protection
• Canonical request serialization

The Python SDK handles this automatically.

Enable globally using:

BUS_REQUIRE_SIGNATURES=true

Admin Auth

Admin endpoints (/admin/*) use separate credentials:

• X-Admin-Token: <BUS_ADMIN_SECRET>
• HTTP Basic auth

Quickstart (CLI)

pip install intent-bus
export INTENT_API_KEY="your_key_here"

Publish a job

intent-bus publish send_notification '{"instruction":"Hello"}' -n default

Run a worker

intent-bus listen send_notification -n default -c notify

Quickstart (Python SDK)

Publish a job

from intent_bus import IntentClient

with IntentClient(api_key="your_key_here") as client:
    published = client.publish(
        goal="send_notification",
        payload={"instruction": "Hello from the cloud"},
        idempotency_key="task_123",
        priority=500,
    )

    print(f"Published: {published.id}")

Job Visibility

• private (default) — only workers using the same API key can claim the job
• public — any authenticated worker in the namespace can claim it

Public jobs should only be used in trusted environments.

Run a worker

from intent_bus import IntentClient, WorkerRuntime

def handler(job):
    print("Received:", job.payload.get("instruction"))

    return {
        "result": "delivered",
        "result_type": "text",
    }

client = IntentClient(api_key="your_key_here")
runtime = WorkerRuntime(client=client)

runtime.listen(
    goal="send_notification",
    handler=handler,
)

Workers must be idempotent. The same job may be delivered more than once if:

• the worker crashes mid-execution
• the lease expires before /fulfill is called
• the network drops after the server marks the job fulfilled but before the response arrives
• the bus retries due to an ambiguous failure

SDK repo: https://github.com/dsecurity49/Intent-Bus-sdk

Quickstart (curl / Bash)

Publish a job

curl -X POST https://your-bus.render.com/intent \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_key_here" \
  -d '{"goal":"send_notification","payload":{"instruction":"Hello"}}'

Publish with priority and delay

curl -X POST https://your-bus.render.com/intent \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_key_here" \
  -d '{"goal":"send_notification","payload":{"instruction":"Urgent"},"priority":900,"delay":5.0}'

Claim and fulfill

# Claim
curl -s -X POST \
  "https://your-bus.render.com/claim?goal=send_notification" \
  -H "X-API-KEY: your_key_here"

# Fulfill
curl -s -X POST \
  "https://your-bus.render.com/fulfill/<INTENT_ID>" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_key_here" \
  -d '{"claim_token":"<TOKEN>","result":"done","result_type":"text"}'

If a job is not fulfilled within 60 seconds, it is automatically requeued with exponential backoff.

Workers should respect the Retry-After header after receiving 204 No Content.

Job Lifecycle

open ──► claimed ──► fulfilled
                │
                ▼
              open (retry with backoff)
                │
                ▼
              dead ──► dead-letter queue

Dead letters can be inspected through admin endpoints and retried later.

Smart Routing

Target a specific worker

client.publish(
    goal="run_backup",
    payload={"instruction": "/data"},
    target_worker="termux-phone-1",
)

Worker:

curl -X POST \
  "https://your-bus.render.com/claim?goal=run_backup" \
  -H "X-API-KEY: key" \
  -H "X-Worker-ID: termux-phone-1"

Require a capability

client.publish(
    goal="transcribe_audio",
    payload={"instruction": "meeting.mp3"},
    required_capability="whisper",
)

Worker:

curl -X POST \
  "https://your-bus.render.com/claim" \
  -H "X-API-KEY: key" \
  -H "X-Worker-Capabilities: whisper,ffmpeg,gpu"

Both fields can be combined.

Example Use Cases

• Trigger a phone notification when a cloud scraper finishes
• Deploy to a Raspberry Pi behind a firewall without opening ports
• Relay alerts to Discord from scripts
• Replace fragile cron pipelines with loosely coupled workers
• Coordinate heterogeneous worker fleets

Features

• Reliable delivery with retries
• Atomic locking
• Cryptographic claim tokens
• Dead-letter queue
• Priority scheduling
• Namespace isolation
• Worker targeting
• Capability matching
• Delayed execution
• Result storage
• Idempotency keys
• Optional HMAC signing
• Admin dashboard
• Prometheus metrics
• Ephemeral KV store

Architecture Guarantees

• Jobs are not silently discarded during normal operation
• Only one worker can hold a valid lease at a time
• Workers can crash safely and jobs will be retried
• Delivery is at-least-once
• Dead intents are archived instead of deleted

Limitations

• SQLite has single-writer contention under high concurrency
• Throughput eventually flattens as contention increases
• Tail latency rises under sustained load
• Not intended as a Kafka replacement
• PostgreSQL is the natural future upgrade path

Setup

Option 1 — PythonAnywhere

Requirement:

python -c "import sqlite3; print(sqlite3.sqlite_version)"

Install:

git clone https://github.com/dsecurity49/Intent-Bus.git
cd Intent-Bus
pip install -r server-requirements.txt

Option 2 — Docker

git clone https://github.com/dsecurity49/Intent-Bus.git
cd Intent-Bus
mkdir -p bus_data && chmod 755 bus_data
docker-compose up -d

Deployment Capacity & Performance

Benchmark runs recorded (v7.61 validation run, 2026-05-24):

Android 12 phone running the server via Termux outperformed the Render free tier at Heavy load. PythonAnywhere free tier is not recommended due to single-threaded request handling.

• 0 network errors
• 0 lease lost
• 0 rate limit errors

Higher concurrency increases tail latency, but the system remains stable under sustained contention.

Stress test running on Android 12 phone via Termux

Performance Benchmarks

Low Profile

Light automation workloads with tightly clustered latency.

Medium Profile

Moderate queue contention with graceful SQLite WAL lock waiting.

High Profile

Sustained concurrent polling and fulfillment with increased tail latency under load.

Throughput Graph

Deployment Recommendations

Recommended

Deploy with Docker on:

• Render
• Railway
• Fly.io
• Heroku

Multi-threaded deployments handle concurrent worker polling more comfortably.

Surprisingly Viable

The server has been stress-tested running directly on an Android 12 phone via Termux, sustaining 28 j/s at A+ grade under heavy load — outperforming a Render free tier container.

Not Ideal

PythonAnywhere free tier is not well suited for high-concurrency worker polling because a single-threaded app process can create backlog under sustained load.

Safe Operating Limits

Based on current testing:

• Safe concurrent workers: ~40
• Sustained throughput: 13+ jobs/sec in tested environments
• Recommended deployment: Docker with multiple app threads
• Default payload size: 8KB per intent/result

Larger payloads can be enabled by increasing:

app.config["MAX_CONTENT_LENGTH"]
MAX_PAYLOAD

Environment Variables

API Reference

Why I built this

I wanted to trigger scripts on my Android phone from a cloud server without Firebase, open ports, or complex infrastructure.

So I built a tiny job bus using Flask + SQLite.

Contributors

• Zan (@ghostframe) — Security auditing and hardening
• Dhanush (@dsecurity49) — Creator and maintainer

License

MIT