Bitween documentation

Bitween is a self-hosted integration platform. It takes business documents in from partners, HTTP calls, message brokers, databases and scheduled pulls. It validates, transforms and delivers them, and keeps a searchable record of every exchange.

One .NET 10 service hosts everything: the REST API, the partner-facing gateway endpoints, background processing, the scheduler and the React admin UI.

These docs are written from the source code as of 11 September 2026. They replace the earlier README and docs/ pages, which described an older version of Bitween.

What Bitween does#

• Many ways in. Partners call an API gateway. Other systems publish to Bitween's bus, or to their own RabbitMQ or Amazon SQS broker. Scheduled jobs pull from HTTP APIs, S3, Azure Blob, SFTP/FTP, POP3 mailboxes and databases. Aggregations roll finished exchanges up on a schedule.
• One pipeline. Every message becomes an exchange that runs through the same stages: filter, map, deliver, route the response.
• Adapters for each stage. Built-in adapters cover HTTP, S3, Azure Blob, SFTP/FTP, POP3 and SMTP, plus a visual rules-based mapper for JSON and XML. Anything else can be a custom adapter that runs out of process.
• Long-lived connections. Data sources hold connections to RabbitMQ and Amazon SQS brokers and to PostgreSQL, MySQL, SQL Server and Oracle databases, so deliveries can publish messages or run SQL.
• Reliability built in. Retry policies match failures and retry them with a delay and a shared budget. Every exchange's retries form a chain you can follow. Exhausted budgets raise alerts, and notifiers report results.
• Operable. Queue health straight from RabbitMQ, data source health, schedule health, run history, receive attempts, a dashboard and an audit trail of every configuration change.
• Administered in the browser. Roles with fine-grained permissions, Microsoft sign-in, and settings and branding that change at runtime.

How it fits together#

flowchart LR
  subgraph In[Entry points]
    GW[API gateway]
    BUS[Bus gateway]
    JOB[Scheduled job]
    AGG[Aggregation]
  end
  subgraph Core[Bitween service]
    X[(Exchange)]
    P[Filter, mapper, handler]
    R[Result and retry policy]
  end
  EXT[(Customer broker or database)]
  EXT --> BUS
  EXT --> JOB
  GW --> X
  BUS --> X
  JOB --> X
  AGG --> X
  X -->|work group queue| P --> R
  P -->|delivery| OUT[Partner systems]
  P -->|publish or SQL| EXT
  R -->|notifiers and alerts| N[Handler adapters]
  X -. files .-> S[(Object storage)]
  R -. rows .-> DB[(Bitween database)]

Requirements#

Quick start#

This runs Bitween locally against PostgreSQL, RabbitMQ and local-disk storage.

1. Start the dependencies.

   docker run -d --name bitween-pg -p 5432:5432 -e POSTGRES_PASSWORD=postgres postgres:16
   docker run -d --name bitween-mq -p 5672:5672 -p 15672:15672 rabbitmq:3-management

2. Build the admin UI into the web host's wwwroot.

   cd SW.Bitween.Web/ClientApp
   yarn install
   yarn build
   cd ../..

3. Configure and run the service.

   export ASPNETCORE_ENVIRONMENT=Development
   export Bitween__DatabaseType=PgSql
   export ConnectionStrings__BitweenDb="Host=localhost;Port=5432;Database=bitween;Username=postgres;Password=postgres"
   export ConnectionStrings__RabbitMQ="amqp://guest:guest@localhost:5672/"
   export Bitween__StorageProvider=Local
   export CloudFiles__BucketName=bitween
   export Token__Key="replace-with-a-random-string-of-at-least-32-chars"
   export Token__Issuer=bitween-local
   export Token__Audience=bitween-local
   export Bitween__RabbitMqManagementUrl=http://localhost:15672
   export Bitween__RabbitMqManagementUsername=guest
   export Bitween__RabbitMqManagementPassword=guest
   
   dotnet run --project SW.Bitween.Web

4. Open https://localhost:5000 and sign in as the seeded administrator.

   [email protected]
   Mtm@dmin!2

The database schema is created on first start. Change the administrator password straight away, and work through the production checklist before exposing an instance. To use brokers or databases as data sources, see Data sources.

Repository layout#

License#

MIT. See LICENSE.