When a single server or a distributed CrowdSec setup fits
A single-server CrowdSec install is the right starting point when one host, or a few hosts that each protect themselves, need to parse their own logs and block attackers locally. In that model the Security Engine, its Local API and the remediation component all run on the same machine, so there is one configuration to maintain and one place to check when a ban does not appear. The distributed model fits when detection and enforcement must sit in different places: many Log Processors feeding one Local API, with bouncers at a firewall, reverse proxy or CDN that block traffic far from where the logs are read. CrowdSec documents both models, and the decision is mostly about where blocks must land and how many hosts share one set of decisions.
The operational gain of distribution is that you parse logs once and enforce everywhere. A single Local API can serve decisions to several bouncers, so an attacker banned from a web log on one host can be blocked at the edge without installing detection on every machine. The cost is more moving parts: the Local API becomes a dependency for every bouncer and every Log Processor, API credentials must be issued and rotated per component, and a network fault between them can leave some enforcement points working from stale decisions. If you run only two or three hosts, or every host already blocks locally and no edge device needs the same decisions, the added architecture is rarely worth it. Confirm your bouncer types and their connection path before you choose.
CrowdSec advises running it next to the log pipeline rather than on production workloads in centralized setups, so a distributed design should place the Security Engine on a separate host beside your central log collector, not on the application servers it protects. Ask your team three questions: how many hosts generate logs that need analysis, which devices must enforce blocks, and who will own the Local API and its credentials. Also confirm current requirements and supported bouncers in the CrowdSec documentation before sizing a central host, because the answers decide whether a single server or a distributed design is the simpler one to run.
Single server and distributed CrowdSec side by side
This table compares running CrowdSec on each server with a distributed design that splits Log Processors, the Local API and remediation components across hosts. Read each row as a question to answer for your own estate, since the right model depends on how many hosts you run and where you enforce decisions. The main takeaway is that the engine and Hub rules cost nothing to license in either model, so the real differences are infrastructure, staff time and how far a single failure reaches.
| Factor | Per-server CrowdSec | Distributed CrowdSec |
|---|---|---|
| Components per host | Log Processor, Local API and bouncer on each machine, managed independently | Log Processors, one or more Local APIs and bouncers split across roles, with fewer components to update on enforcement points |
| Where log parsing happens | On the host that owns the logs, so detection runs close to the source | On dedicated Log Processors that read logs from one or more hosts or a central log pipeline |
| Where decisions are enforced | Local firewall or proxy on the same machine that detected the attack | Firewall, reverse proxy or CDN bouncers that may sit far from the Log Processor that detected the attack |
| Local API placement | One Local API per server, so each host keeps working if others are down | A central Local API that all Log Processors and bouncers reach over HTTP, so its placement is a design decision to confirm |
| Failure impact | A failed host loses only its own detection and blocking, with no shared dependency | A failed Local API can stop decision flow to every bouncer, so confirm the failover and restart procedure before go-live |
| Upgrade sequencing | Each host upgrades on its own schedule, which is simple but multiplies version drift | Upgrade the Local API first and keep Log Processors and bouncers within the versions your CrowdSec release notes support (confirm the compatibility rule for your version) |
| Monitoring | Check each host's service health and decision counts separately | Monitor the Local API, the links to each bouncer and the Log Processor queues, which need a central view |
| Skills needed | Linux administration and basic CrowdSec configuration on every host | Distributed-systems troubleshooting, API authentication and network segmentation between roles |
| Cost drivers | Staff time repeated per host and more machines running the engine; licensing is MIT in both models | Fewer Log Processors to maintain but more design, testing and monitoring work up front; confirm the sizing with your own traffic volume |
How the Local API, Log Processors and bouncers split the work
The Local API (LAPI) is the hinge of a distributed CrowdSec design. According to the CrowdSec documentation, the LAPI connects Log Processors to remediation components and to the Central API, and every component talks to it over an HTTP API. That HTTP interface is what makes a multi-machine setup possible: a Log Processor that detects an attacker records a decision with the LAPI, and bouncers pick that decision up from the LAPI and enforce it locally. The LAPI is therefore the component to design around first, because the other roles depend on it being reachable and on each machine authenticating to it correctly.
Remediation is handled by bouncers, which block malicious IPs at layers such as iptables, firewalls, web servers or reverse proxies. The CrowdSec repository's comparison with fail2ban makes the key operational point: detection and remediation are separate. One machine can parse logs while another blocks traffic at a firewall, reverse proxy or CDN. In practice this means a Log Processor can sit beside your central log pipeline while bouncers sit at the edge where traffic actually lands. Confirm with the CrowdSec documentation which bouncer types match your firewall, proxy or CDN before you commit to this split, since support depends on the component you run.
Decide early which role each host plays and what happens when the LAPI is unreachable. A bouncer that cannot reach the LAPI cannot receive new decisions, so you should plan how it keeps enforcing existing ones and how you will alert on the gap. Log Processors that cannot reach the LAPI will stop reporting detections. Test both failure modes in a non-production environment and document the result, since the CrowdSec introduction describes the architecture but does not set the recovery behavior for your topology.
Components and topology of each deployment
CrowdSec splits work across an engine that parses logs, a Local API that holds decisions, and bouncers that enforce them. Where you place each piece sets your failure domains, your upgrade sequence and how much of your network depends on one service. The cards below cover the layouts CrowdSec documents and the condition under which each one fits.
Single host with engine and bouncer
Engine, parsers, Local API and a bouncer all run on one machine, which is the simplest layout and the one most small fleets start with. Detection and enforcement share a host, so a failure on that host removes both protection and blocking at once. This layout fits a few servers that you manage individually. Confirm that the host has enough headroom to parse its own logs and that you have a tested way to restore its configuration and local decisions.
Distributed Local API with remote Log Processors
One Local API receives decisions from several Log Processors on other machines, so detection can run close to each log source while decisions stay in one place. This is the layout to consider when several servers must share one set of bans and one reporting point. The Local API becomes the central dependency: if it is unreachable, Log Processors cannot pass decisions onward. Confirm how each component authenticates to the Local API, how credentials rotate, and what each side does while the link is down.
Bouncers at the firewall, proxy or CDN
Remediation components can run at a firewall, reverse proxy or CDN edge, separate from the machine that parsed the logs. Blocking happens where traffic enters, which is useful when the parsing host is not in the traffic path. Each bouncer must reach the Local API to pull decisions, so its refresh behavior and its fail-open or fail-closed setting determine what happens during an outage. Confirm which bouncer types your edge supports and how they are updated.
Co-location next to a central log pipeline
CrowdSec can run beside a centralized log pipeline, such as a shipper and collector that gather logs from many hosts. The engine then reads a single stream instead of agents on every server. CrowdSec's documentation advises running next to the log pipeline rather than on production workloads in centralized setups, so this placement suits a dedicated security host. Confirm that the pipeline preserves the fields your scenarios need and that log delivery delay is acceptable for your blocking goals.
WAF-only and AppSec placement
The AppSec component filters HTTP requests from compatible web servers and is built on Coraza with OWASP Core Rule Set support. It can be deployed in a WAF-only mode, which means the web tier is protected without running log-based scenarios on that host. This layout fits when the main risk is application-layer attack traffic rather than SSH or service brute force. Confirm which web server and bouncer pairs are supported, and test false positives against your real application before enforcing.
Containers and Kubernetes deployment
CrowdSec documents deployment in containers and on Kubernetes, so the same component roles can be scheduled as workloads. Config, hub content and the database must sit on persistent storage, and the Local API address must stay stable across restarts and rescheduling. Confirm how your cluster exposes the Local API internally, whether bouncers run as sidecars or as cluster-wide components, and how you back up and roll back the configuration when you upgrade the image.
What changes when a component fails
The main difference between the two models is where a failure lands. On a single server, a crash takes detection and enforcement down together, because the Security Engine parses logs and applies its own decisions on the same host. In a distributed design, the Local API (LAPI) is the central piece: if it is unavailable, Log Processors can keep detecting but cannot publish new decisions, and bouncers at the firewall, proxy or CDN can only enforce what they already hold. Losing one Log Processor is a narrower problem, because it stops parsing only the logs it reads, and the other processors and bouncers keep working. Before going live, map which host or service each log source depends on and write down what goes silent when each one stops.
Decision caching is the setting that decides how much enforcement survives a LAPI outage. Bouncers hold decisions locally and can keep enforcing them while the API is unreachable, but the length of that protection and what happens to new attacks during the gap depend on the bouncer type, its configuration and your CrowdSec version. Confirm the cache behavior, expiry and the bouncer's fallback action in the CrowdSec documentation for the exact release you run. Then test it: stop the LAPI in a staging copy, replay a known attack pattern, and check which bouncers still block, for how long, and what the logs record when they cannot reach the API.
Run the same test for each failure type, not only the obvious one. Stop one Log Processor and confirm the remaining ones still raise alerts for the sources they cover. Stop a bouncer and confirm the failure is visible to your monitoring, since a silent enforcement gap is harder to spot than a stopped detector. Restore the LAPI and check that decisions resynchronize without manual cleanup. Record the observed results in your runbook, and treat any gap you cannot close, such as a single LAPI with no standby, as a documented accepted risk with a named owner.
Upgrades, backups, monitoring and skills for each model
How do you sequence upgrades when the Local API and bouncers run on different hosts?
Upgrade the Local API first, then the Log Processors that talk to it, then the remediation components at the firewall, proxy or CDN edge. The order matters because the LAPI is the hub that every other component reaches over HTTP, so a bouncer or agent running a newer build than the LAPI may not behave as documented. Plan a maintenance window for each host, confirm that decisions still flow after each step, and keep a rollback path for the LAPI host. Check the compatibility matrix on the CrowdSec releases page before you pick a target version. The current CrowdSec release we reference is 1.8.1, published on September 3, 2026, so confirm that version's notes before planning.
What must you back up in a single-server CrowdSec setup?
On a single server, one host holds the configuration, the local decision database, the acquisition settings and any custom scenarios, parsers or AppSec rules. Back up the CrowdSec configuration directory, the local database, the bouncer configuration and API keys, and any custom rule files kept outside the Hub-managed set. Test a restore on a second machine, because a backup you have never restored is an assumption, not a recovery plan. The Hub content can be reinstalled, but your local tuning and allowlists cannot, so record them in version control.
What must you back up in a distributed CrowdSec deployment?
A distributed design spreads state across roles, so the backup inventory grows with each role. The LAPI host needs its configuration, database and credentials for the Log Processors and bouncers. Each Log Processor needs its acquisition files and any local parsers or scenarios. Each remediation component needs its own bouncer configuration and key. Keep a written map of which key belongs to which host, because a restored LAPI with mismatched credentials will silently reject clients. Store secrets in your normal secrets tooling, not in plain configuration files, and rehearse restoring the LAPI alone.
How do you monitor decisions and component health in CrowdSec?
Monitor three layers: whether each component process is running, whether Log Processors are still reading their sources, and whether bouncers are receiving decisions from the LAPI. Use the CrowdSec command line tools to list active decisions and metrics, and confirm bouncer registrations and last-pull times on the LAPI host. Alert when a bouncer stops polling, when a log source goes silent, or when the decision count drops to zero unexpectedly. A failure at the LAPI means remediation stops at every edge at once, so treat LAPI availability as the primary signal. Ask your team how these checks fit with your existing monitoring stack before you commit to a design.
What skills does a team need to run each CrowdSec model?
A single server needs Linux administration, log source knowledge, and comfort editing YAML acquisition files and scenario tuning. A distributed design adds network and service design: HTTP connectivity between hosts, TLS and credential handling, firewall rules that allow bouncers to reach the LAPI, and a clear owner for each role. Teams that also run a WAF through AppSec need familiarity with web server integration and the rule formats CrowdSec uses. Assess whether your engineers already manage similar multi-host services, and factor in staff time for false positive review, which exists in both models.
How do you check that CrowdSec components are on compatible versions?
Confirm that every Log Processor, LAPI and bouncer is built for the same release line before you roll out changes. Check the compatibility guidance and release notes on the CrowdSec releases page, since version support between bouncers and the engine is what determines whether communication works. Record each host's installed version in your inventory, and check it after every upgrade wave. Where a bouncer ships separately from the engine, track its version as its own line item. If the documentation for your chosen bouncer is unclear, confirm the supported pairing with CrowdSec before rollout.
Can your own team run a distributed CrowdSec deployment, or do you need outside help?
Your team can run it if it already operates multi-host Linux services, has an on-call rotation, and can own the LAPI as a critical dependency. Outside help is most useful when you need the design, hardening and runbooks written before go-live, or when you want the environment tested under failure. DeployOpen plans, implements, documents and supports self-hosted open-source platforms inside your own infrastructure, typically under a fixed scope agreed in writing before work starts, with ongoing support available as a retainer. A written scope is the basis for a quote, and DeployOpen does not publish a price list. Ask any provider to state which upgrade, backup and monitoring tasks stay with your staff afterward.
How to move from per-server installs to a central Local API
This sequence moves a fleet of standalone CrowdSec installs to one Local API with separate Log Processors and remediation components, so detection and enforcement can be managed, tested and rolled back in controlled stages.
Inventory hosts, log sources and current decisions
The platform or security engineer lists every server running a CrowdSec engine, the log files and HTTP sources each one reads, the collections and scenarios installed, and the bouncers that enforce decisions on each host. Record which hosts sit behind a firewall, reverse proxy or CDN, since those points usually enforce decisions and do not need their own engine. Record which hosts already send logs to a central pipeline. The step is done when you have one table that maps every host to its sources, detection content and enforcement point, and the owner has signed off on it.
Decide where each bouncer enforces
The security architect and the owners of the firewall, proxy and web tier decide which enforcement point blocks traffic for each group of hosts. Typical choices include a host firewall for SSH, a reverse proxy or web server bouncer for HTTP services, and a CDN or edge bouncer where one is in use. Document which bouncer type, API key and network path each group will use to reach the Local API, and which groups keep a local fallback. The step is done when every enforcement point has a named owner and a written mapping to a Local API address.
Stand up the Local API and Log Processors in a test environment
The platform engineer builds one Local API instance and one or more Log Processors in a non-production environment, using the architecture in the CrowdSec documentation for multi-machine setups. Configure the Log Processors to read the log sources from the inventory and point the bouncers at the test Local API. Confirm that the Local API connects to the Central API for shared decisions and blocklists, and that each component authenticates over the HTTP API. Confirm the exact configuration keys and versions against the CrowdSec release you plan to run, for example 1.8.1 as published on September 3, 2026, and the current documentation. The step is done when a test attack on a sample host produces a decision that a test bouncer enforces.
Move bouncers one group at a time
The operations team switches one group of enforcement points, such as a single web tier, from its local engine to the central Local API, then leaves the other groups unchanged. Keep the previous local configuration in place so the group can be reverted quickly. Use the same change window and approval process you apply to other production changes, and agree the rollback trigger before the change starts. Repeat for each group in the order you chose in the enforcement mapping. The step is done when each group has run in production with the central Local API and no unexplained blocks or gaps are recorded in its logs.
Verify decisions and failover
The security engineer tests the design under normal and failure conditions. Confirm that a decision created by one Log Processor reaches bouncers in every group, that expected allowlists still apply, and that a sample of legitimate traffic is not blocked. Then simulate a Local API outage in the test environment and record what each bouncer does, since the behavior depends on the bouncer type and its configuration. Decide how long a host can operate without the Local API, and document the recovery steps. The step is done when the test results, failure behavior and recovery procedure are reviewed and accepted by the operations owner.
Confirm monitoring and access controls for the central components
The platform team connects the Local API and Log Processors to the team's monitoring and alerting, and restricts access to the Local API, its credentials and the machine accounts that bouncers use. Confirm that logs from each component reach the central pipeline if your design requires it, and that alerts fire when a Log Processor stops reading a source or a bouncer stops polling. Review who can create or delete decisions and who can change scenarios. The step is done when alerts for component health have been tested and the access list has been recorded in the runbook.
Retire per-host engines
Once every group has run on the central design through a full review period agreed with the owner, the operations team stops and removes the standalone CrowdSec engines on hosts that no longer need them. Remove their local bouncer configuration only after the central path is confirmed, and keep a dated record of what was removed. Update the inventory, runbooks and on-call documentation so the new topology is the only one in use. The step is done when the inventory shows no orphaned engines, every bouncer points to the central Local API, and the change record is filed.
Choosing the model that fits your fleet
One host per install is the right default when you run a handful of servers, the networks are isolated from each other, and one or two people own security operations. In that model every server runs the full stack: a log processor that parses local logs, a Local API, and a bouncer that blocks at the local firewall. Nothing depends on a second machine, so a single failure affects one host. The trade-off is that each server keeps its own decisions, its own scenarios and its own upgrade cycle, so policy drift grows with every host you add. Before you commit, confirm that the community blocklist sharing you want is available on each install and that your team can run the upgrade routine on every node.
A distributed design fits when you have many hosts, enforcement must happen at the edge (a firewall, reverse proxy or CDN), or logs already flow into a central pipeline. One Local API receives events from several Log Processors and serves bouncers across the estate, so a decision made once applies everywhere it is enforced. The cost is a new central dependency: if the Local API is unreachable, bouncers depend on whatever decision cache and failure behavior they were configured with, and log processors may queue or drop events. Test that behavior deliberately by stopping the Local API in a non-production environment and watching what each bouncer does. CrowdSec advises running it next to the log pipeline rather than on production workloads in centralized setups, so plan a dedicated host for it.
Mixed designs are common and often the practical answer. You might keep a standalone install on an isolated network segment while a central Local API serves the rest of the fleet, or run Log Processors near the logs and bouncers at the perimeter. Decide per network zone, not for the whole estate at once. Write down who owns the Local API, how credentials for each machine are issued and rotated, and which team gets paged when a bouncer loses its connection. For the exact deployment steps and the component roles, start with the CrowdSec documentation introduction.
How DeployOpen scopes a CrowdSec deployment
The sequence turns a single-server or distributed CrowdSec idea into a written architecture, a working detection and remediation path inside your own infrastructure, and documentation your operations team can run. Most engagements are fixed-scope, with deliverables agreed in writing before work starts.
Inventory log sources and enforcement points
DeployOpen starts by listing every host, web server, reverse proxy, firewall, CDN origin and container platform that produces logs or needs to block traffic, along with where each one runs and who owns it. The inventory records which logs must be parsed, which enforcement points can accept decisions, and where network segmentation limits traffic between them. The output is a written source and enforcement map that the client signs off before any architecture decision is made.
Decide single server or distributed layout
Using the inventory, the team compares a per-server layout, where each host runs its own engine and local bouncer, with a distributed layout, where one Local API serves several Log Processors and remediation components at the firewall, proxy or CDN. The decision record covers which component handles which failure, where the Local API and its database live, and who operates each part. CrowdSec documents both single-machine and multi-machine deployments, and the choice is confirmed against the client's change process and on-call model.
Design the Local API and trust boundaries
If the design is distributed, DeployOpen defines where the Local API runs, how Log Processors and bouncers authenticate to it over its HTTP API, and which network paths are allowed. The design also states what happens when the Local API is unreachable, so bouncers and processors have a documented fallback and alert. The output is a diagram and an access matrix that the client's security and network teams review.
Integrate bouncers and log sources
DeployOpen installs and configures the log acquisition for each source and connects each remediation component, such as iptables, a firewall, a web server or a reverse proxy, to the Local API. Where AppSec is in scope, the team confirms which compatible web servers send HTTP requests to it and tests the blocking path end to end. Done means a controlled test event is detected, a decision is created, and the expected enforcement point blocks it, with results recorded per source.
Harden the deployment
DeployOpen applies the client's hardening baseline to the engine, Local API, bouncers and the hosts they run on. Work covers credential handling for machine and bouncer keys, file permissions, service accounts, network restrictions on the API port, and whether community blocklist sharing is enabled under the client's data-sharing policy. Completion is confirmed by a hardening checklist that the client's security team reviews and accepts in writing.
Document operations and failure handling
DeployOpen writes runbooks for routine operations, including upgrades, adding a server, rotating keys, reviewing decisions and handling a Local API outage. The documentation also records which failures fail open or closed at each enforcement point, and the monitoring signals that reveal them. The output is a handover pack that operations staff can follow without the implementation team present.
Agree support and upgrades in writing
The scope closes with a written statement of deliverables, acceptance criteria and any follow-on work. Ongoing support, upgrades and continuous testing are available as a retainer, which the client can add after handover or keep out of scope. Pricing follows from the written scope, and DeployOpen does not publish a price list, so the client should ask for a quote that separates one-time implementation from any recurring support.
How DeployOpen delivers and supports CrowdSec deployments
DeployOpen plans and implements self-hosted open-source platforms inside the client's own cloud accounts, data centers or air-gapped networks. For CrowdSec single server vs distributed setup, the work starts with a written scope that decides where the Local API, Log Processors and remediation components should run in your environment.
How we scope
- Map which servers parse logs and which enforce decisions at firewalls, proxies or CDNs.
- Record the written scope, deliverables and timeline before any configuration work begins.
- Confirm the Local API placement, network paths and failure behavior each server type needs.
How we build
- Deploy the Local API, Log Processors and bouncers according to the agreed topology.
- Test blocking behavior and decision propagation at each remediation point in staging.
- Harden the API connections, credentials and component configuration to your security baseline.
How we hand over
- Document the architecture, component roles and the recovery steps for a Local API outage.
- Walk your operations and security teams through alert review and decision management.
- Deliver runbooks for upgrades, certificate rotation and adding new servers to the design.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers.
- Retainer scope can cover reviewing CrowdSec releases and applying upgrades in your environment.
- Confirm response expectations and coverage hours in the written retainer before work starts.
