Targets

A Target is a machine where deployments execute. Each target runs the Tarsus agent, which registers and sends heartbeats directly to Mandible. Mandible assigns a Thorax orchestration instance, and commands are executed against the target through that Thorax instance.

What is a Target?

Targets represent the actual infrastructure where your code runs:

• Physical servers
• Virtual machines
• Cloud instances
• Containers (with persistent Tarsus installation)

Target Properties

Property	Description
Name	Display name (e.g., “web-prod-01”). Not enforced unique — no uniqueness constraint exists.
Mode	Connection mode (Listen or Poll)
Hostname	Network address
Port	Tarsus listening port (default: 9342)
Status	Online, Stale, or Offline
Tags	Key-value labels for grouping

Connection Modes

Targets connect to Mantis in one of two modes:

Listen Mode

Tarsus runs a gRPC server; Thorax initiates connections.

Best for:

• Stable, routable IP addresses
• Controlled network environments
• Low-latency requirements
• When inbound firewall rules are allowed

Characteristics:

• Thorax pushes commands to Tarsus
• Lower latency (immediate execution)
• Requires inbound network access to target

Poll Mode

Tarsus initiates all connections to Thorax (outbound only).

Best for:

• Machines behind NAT or restrictive firewalls
• Cloud instances with dynamic IPs
• Networks with outbound-only rules
• Complex network topologies

Characteristics:

• Tarsus pulls commands from Thorax periodically
• Configurable poll interval (default: 30 seconds)
• Higher latency (commands wait for next poll)
• Only requires outbound gRPC (TLS) access to Mandible and Thorax

Target Status

Targets have three health states:

Status	Badge	Description
Online	Teal	Active connection, healthy (green in the high-contrast theme)
Stale	Orange	No recent heartbeat, may be recovering (yellow in high-contrast)
Offline	Crimson	No active connection (red in high-contrast)

Status renders as a coloured text badge, not an icon/glyph.

Status Transitions

Last Seen - Shows when the target last communicated (e.g., “2 hours ago”).

Target Registration

When a Tarsus agent starts, it registers with Mandible:

Automatic Registration

1. Tarsus connects to Mandible with its certificate
2. Mandible checks if the certificate thumbprint is known
3. If new, the registration enters “Pending” state
4. Administrator approves the registration
5. Target becomes active

Token-Based Registration

For zero-touch provisioning:

1. Administrator generates a registration token in Lens
2. Token is provided to Tarsus configuration
3. Tarsus registers using the token
4. Registration is approved only if the token has auto-approve enabled (it defaults to OFF — a secure default; otherwise the registration stays pending for manual approval)
5. Token use count is incremented (tokens are unlimited-use by default; set max_uses to limit reuse)

Tip

Use registration tokens for automated provisioning in cloud environments or CI/CD pipelines.

Managing Targets

Viewing Targets

1. Open the Infrastructure group in the top navigation, then the Targets pill
2. View the target list with status indicators
3. Filter by status (the API accepts page/per_page/search/tenant_id plus a status filter; search and status both run in SQL and span every page, and there is no tag or environment filter)
4. Search by name or hostname

Creating a Target

Targets are typically auto-created when a Tarsus agent registers. To create manually:

1. Click New Target
2. Enter name and hostname
3. Select connection mode
4. Configure port (default: 9342)
5. Save

Editing a Target

1. Click on a target in the list
2. Modify properties as needed
3. Save changes

Deleting a Target

1. Click on a target in the list
2. Click Delete
3. Confirm deletion

Caution

Deleting a target removes it from all environments. The Tarsus agent will need to re-register.

Target Tags

Tags are key-value pairs for organizing and selecting targets:

Tag Key	Tag Value	Purpose
environment	production	Environment grouping
role	web	Server role
region	us-east-1	Geographic location
tier	frontend	Application tier

Managing Tags

1. Open target detail page
2. Navigate to Tags section
3. Add, edit, or remove tags
4. Save

Using Tags for Deployment

Tags enable flexible target selection:

• Deploy to all targets with role=web
• Deploy to region=us-east-1 AND environment=production
• (Tag selection is include-only — by id or by tag with ANY/ALL matching. There is no tag exclusion, so you cannot exclude maintenance=true targets by tag; deselect them manually.)

Target Environments

Targets can be assigned to one or more environments:

Priority Within Environments

Targets have a priority within each environment, which orders them in a promotion or rollback:

Target	Priority	Order
prod-web-1	100	First
prod-web-2	75	Second
prod-web-3	50	Third
prod-db-1	10	Last

Higher priority values run first. Priority ranges from -100 to 100 and defaults to 50. An ordinary deployment runs the targets its request names, in the order named.

Health Monitoring

Dashboard View

The dashboard shows target health at a glance:

• Total Targets - All registered targets
• Online - Healthy, active targets
• Stale - Targets needing attention
• Offline - Unavailable targets
• Recent Activity - a deployment-event timeline (not target last-seen timestamps)

Troubleshooting Offline Targets

If a target shows offline:

1. Check the agent - Is Tarsus running on the machine?
2. Check networking - Can the target reach Thorax (poll) or be reached (listen)?
3. Check certificates - Are TLS certificates valid and not expired?
4. Check firewall - Are required ports open?
5. Review logs - Check Tarsus logs for errors

Best Practices

Naming Conventions

Use consistent, descriptive names:

{role}-{environment}-{number}
web-prod-01
db-staging-01
worker-dev-01

Tag Strategy

Create a tagging taxonomy:

Category	Example Tags
Environment	env:dev, env:staging, env:prod
Role	role:web, role:api, role:worker
Region	region:us-east, region:eu-west
Team	team:platform, team:payments

Registration Security

• Review pending registrations promptly
• Use registration tokens for automated provisioning
• Rotate tokens after use
• Monitor for unexpected registration attempts

Next Steps

• Managing Targets - Detailed target operations
• Listen vs Poll Mode - Connection mode details
• Health Status - Understanding target health
• Tagging - Tag strategies