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, written in .NET, Python, JavaScript or TypeScript, that runs out of process. The bitween CLI writes, checks and publishes them, and Python, JavaScript and TypeScript adapters can also be written in the admin UI.
• 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 subscriptions report their results, both through notification channels: Email, Microsoft Teams, Slack or any adapter, each set up once.
• 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 -->|notifications and alerts| N[Notification channels]
  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__InitialAdminPassword="replace-with-your-own-password"
   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 [email protected] with the password you set in Bitween__InitialAdminPassword.

The database schema is created on first start. A new database refuses to start without Bitween__InitialAdminPassword (see Configuration). Work through the production checklist before exposing an instance. To use brokers or databases as data sources, see Data sources.

Repository layout#

License#

Bitween is licensed under the GNU Affero General Public License v3.0, with the additional terms in NOTICE:

• You can use, run and modify Bitween for free, including in production inside your organization.
• If you distribute Bitween or offer it as a service to others, you must release your source code under the AGPL and keep the "Based on Bitween by Simplify9" attribution.
• Forks and modified versions must use a different name. "Bitween" is a Simplify9 trademark.
• SW.Bitween.Sdk (the SimplyWorks.Bitween.Sdk NuGet package) and the SW.Bitween.Sample* projects stay under the MIT License, so your custom adapters can use any license.
• Versions released before the license change remain available under the MIT License.

A commercial license is available from Simplify9 ([email protected]) for embedding Bitween in closed-source products or hosting it for third parties without releasing source code.