Listen vs Poll Mode

Targets can connect to Mantis in two modes, each suited to different network environments.

In both modes, the Tarsus agent registers and sends heartbeats directly to Mandible. The connection mode only changes how commands are delivered for execution: in Poll mode Tarsus polls its assigned Thorax instance for commands, while in Listen mode a Thorax instance connects inbound to push commands.

Connection Modes Overview

Mode	Direction	Best For
Listen	Thorax → Tarsus	Routable targets, low latency
Poll	Tarsus → Thorax	NAT/firewall, dynamic IPs

Listen Mode

In Listen mode, the Tarsus agent runs a gRPC server, and Thorax initiates connections.

How It Works

1. Tarsus starts and listens on configured port (default: 9342)
2. Tarsus registers with Mandible, providing its address
3. Thorax connects to Tarsus when commands are available
4. Commands execute immediately upon connection

Network Requirements

Requirement	Details
Inbound port	9342 (or configured port)
Firewall rule	Allow Thorax IP → Target:9342
DNS/IP	Target must be routable from Thorax
TLS	mTLS connection with certificates

Advantages

Advantage	Description
Low latency	Commands execute immediately
Real-time	Instant response to deployments
Efficient	No polling overhead
Simple	Direct connection model

Disadvantages

Disadvantage	Description
Network exposure	Requires inbound access
Firewall rules	Must configure inbound rules
Dynamic IPs	Problematic if IP changes
NAT complexity	Difficult behind NAT

When to Use

• Servers with static IPs
• Cloud instances with stable DNS
• Controlled network environments
• Low-latency requirements
• On-premises data centers

Configuration

Tarsus configuration:

# Operating mode: "listen" or "poll"
mode = "listen"

[listen]
# Address to bind to (0.0.0.0 for all interfaces)
address = "0.0.0.0"
# Port to listen on (default: 9342)
port = 9342

Poll Mode

In Poll mode, Tarsus initiates all connections to Thorax, polling for commands.

How It Works

1. Tarsus registers and heartbeats outbound to Mandible, which assigns a Thorax instance
2. Tarsus periodically polls its assigned Thorax for pending commands
3. When commands are available, Tarsus fetches and executes them
4. Results are sent back to Thorax

Network Requirements

Requirement	Details
Outbound access	gRPC (TLS) to Thorax server
Firewall rule	Allow Target → Thorax:50051
DNS	Thorax must be resolvable
TLS	Standard TLS (client certificate optional)

Advantages

Advantage	Description
NAT-friendly	Works behind NAT
Firewall-simple	Only outbound rules needed
Dynamic IPs	Works with changing IPs
Cloud-native	Ideal for auto-scaling

Disadvantages

Disadvantage	Description
Latency	Commands wait for next poll
Overhead	Regular polling requests
Delay	Poll interval affects responsiveness

When to Use

• Machines behind NAT
• Cloud instances with dynamic IPs
• Networks with outbound-only rules
• Container environments
• Edge locations

Configuration

Tarsus configuration:

# Operating mode: "listen" or "poll"
mode = "poll"

[mandible]
# Mandible internal gRPC endpoint used for registration (host:port).
# Mandible assigns a Thorax instance to poll during registration.
# Env: TARSUS__MANDIBLE__ENDPOINT (default localhost:50052)
endpoint = "mandible.example.com:50052"

[poll]
# Polling interval in seconds
interval_secs = 30
# Maximum commands to fetch per poll
max_commands = 10

Poll Interval Tuning

Interval	Latency	Overhead	Use Case
10s	Low	High	Frequent deployments
30s	Medium	Medium	Standard (default)
60s	Higher	Low	Infrequent deployments
300s	Very high	Very low	Rare updates

Comparison

Aspect	Listen	Poll
Latency	Immediate	Up to poll interval
Network direction	Inbound to target	Outbound from target
Firewall complexity	Higher	Lower
NAT support	Poor	Excellent
Dynamic IP support	Poor	Excellent
Server load	Lower	Higher (polling)
Scalability	Very high	High
Deployment responsiveness	Instant	Delayed

Choosing a Mode

Decision Tree

Common Scenarios

Scenario	Recommended Mode
On-premises server with static IP	Listen
AWS EC2 with elastic IP	Listen
Behind corporate firewall	Poll
Home/office with dynamic IP	Poll
Kubernetes pod	Poll
Container in Docker	Poll (or Listen with port mapping)
Cloud VM without public IP	Poll
Load-balanced cluster	Poll

Hybrid Environments

You can mix modes in the same environment:

Production Environment:
├── web-prod-01 (Listen) - DMZ with static IP
├── web-prod-02 (Listen) - DMZ with static IP
├── worker-01 (Poll) - Private subnet
└── worker-02 (Poll) - Private subnet

Changing Modes

To change a target’s mode:

1. Update Tarsus configuration
2. Restart Tarsus agent
3. Update target in Lens (if needed)
4. Verify connection

Caution

Mode changes require Tarsus agent restart. Plan for brief disconnection.

Troubleshooting

Listen Mode Issues

Target shows offline:

• Check inbound firewall rules
• Verify Thorax can reach target:port
• Check TLS certificate validity
• Review Tarsus logs

Connection refused:

• Verify Tarsus is running
• Check port is correct
• Confirm no other service using port

Poll Mode Issues

Target shows offline:

• Check outbound connectivity
• Verify Thorax URL is correct
• Check DNS resolution
• Review Tarsus logs

High latency:

• Reduce poll interval
• Check for network latency
• Consider switching to Listen mode if possible

Security Considerations

Listen Mode Security

• Expose only to Thorax servers
• Use mTLS for authentication
• Rotate certificates regularly
• Monitor for unauthorized access

Poll Mode Security

• Use HTTPS only
• Validate server certificate
• Use client certificates when possible
• Monitor polling patterns

Best Practices

1. Default to Poll for Cloud

Cloud environments often have:

• Dynamic IPs
• NAT gateways
• Restrictive inbound rules

Poll mode works better in these cases.

2. Use Listen for Low Latency

When milliseconds matter:

• Real-time deployments
• Rapid iterations
• Time-sensitive operations

3. Document Mode Choices

Track why each target uses its mode:

Target	Mode	Reason
web-prod	Listen	Static IP in DMZ
worker-prod	Poll	Private subnet, no inbound
dev-local	Poll	Developer machine, dynamic IP

4. Plan for Failover

Consider what happens if:

• Listen mode: Thorax can’t reach target
• Poll mode: Target can’t reach Thorax

Have monitoring and alerting in place.

Next Steps

• Managing Targets - Target management
• Health Status - Understanding health
• Overview - Return to targets overview