Managing Targets

This guide covers day-to-day target management operations in Mantis.

Viewing Targets

Target List

Open the Infrastructure group in the top navigation, then the Targets pill to see all registered targets:

┌─────────────────────────────────────────────────────────┐
│  Targets                                 [New Target]   │
├─────────────────────────────────────────────┬───────────┤
│  Filter: [All        ▼]  Search: [        ] │ 12 total  │
├─────────────────────────────────────────────┴───────────┤
│                                                         │
│  ┌─────────────────┬────────┬──────────┬────────────┐   │
│  │ Name            │ Status │ Mode     │ Last Seen  │   │
│  ├─────────────────┼────────┼──────────┼────────────┤   │
│  │ web-prod-01     │ ● Online│ Listen  │ Just now   │   │
│  │ web-prod-02     │ ● Online│ Listen  │ 2 min ago  │   │
│  │ web-prod-03     │ ◐ Stale │ Listen  │ 15 min ago │   │
│  │ db-prod-01      │ ● Online│ Poll    │ 30 sec ago │   │
│  │ worker-01       │ ○ Offline│ Listen │ 2 hours ago│   │
│  └─────────────────┴────────┴──────────┴────────────┘   │
│                                                         │
└─────────────────────────────────────────────────────────┘

Filtering

Filter targets by:

Filter	Options
Status	All, Online, Stale, Offline

Search

Search by:

• Target name
• Hostname

Target Details

Click a target to view details:

┌─────────────────────────────────────────────────────────┐
│  Target: web-prod-01                                    │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  Status:       ● Online                                 │
│  Mode:         Listen                                   │
│  Hostname:     web-prod-01.company.com                  │
│  Port:         9342                                    │
│  Last Seen:    Just now                                 │
│                                                         │
│  ─────────────────────────────────────────────────────  │
│                                                         │
│  (No environment section — environment membership is    │
│   managed on the environment's own Targets tab,         │
│   /environments/{id}/targets, not here.)                │
│                                                         │
│  Tags:                                                  │
│    role: web                                            │
│    region: us-east-1                                    │
│    tier: frontend                                       │
│                                                         │
│  ─────────────────────────────────────────────────────  │
│                                                         │
│  [Edit]  [Delete]                                       │
│                                                         │
└─────────────────────────────────────────────────────────┘

Creating Targets

Targets are typically created automatically when Tarsus agents register. To create manually:

Manual Creation

1. Click New Target
2. Enter target details:

┌─────────────────────────────────────────────────────────┐
│  Create Target                                          │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  Name:         [web-staging-01                  ]       │
│  Hostname:     [web-staging-01.company.com      ]       │
│  Port:         [9342                           ]       │
│                                                         │
│  Mode:         ● Listen  ○ Poll                         │
│                                                         │
│                           [Cancel]  [Create]            │
└─────────────────────────────────────────────────────────┘

From Registration

When a Tarsus agent registers:

1. Check Registrations page
2. Review pending registrations
3. Click Approve. This marks the registration approved; the target is created on the agent’s next registration, not by the click itself.

Editing Targets

Editable Properties

Property	Can Edit	Notes
Name	Yes	Display name (not enforced unique)
Hostname	Yes	Update if IP changes
Port	Yes	Match Tarsus config
Mode	Yes	May require Tarsus restart

Update Process

1. Open target details
2. Click Edit
3. Modify properties
4. Click Save

Note

Changing hostname or port may require updating the Tarsus agent configuration.

Environment Assignment

Adding to Environment

1. Open the environment, then its Targets tab (/environments/{id}/targets)
2. Click Add Target
3. Select the target
4. Set priority
5. Save

The target detail page has no environment control — membership is managed from the environment’s own Targets tab, which calls POST /environments/{environment_id}/targets to assign and PATCH or DELETE /environments/{environment_id}/targets/{target_id} to change or remove.

┌─────────────────────────────────────────────────────────┐
│  Add Target to Staging                                  │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  Target:       [web-staging-01                     ▼]     │
│  Priority:     [50                               ]      │
│                                                         │
│  ┌───────────────────────────────────────────────────┐  │
│  │ Priority orders promotions and rollbacks.        │  │
│  │ Higher values run first.                         │  │
│  └───────────────────────────────────────────────────┘  │
│                                                         │
│                           [Cancel]  [Add]               │
└─────────────────────────────────────────────────────────┘

Removing from Environment

1. Open the environment’s Targets tab
2. Click Remove next to the assignment
3. Confirm removal

Priority Management

In a promotion or rollback, higher priority values run first (range -100 to 100, default 50) and ties run in target-ID order:

Target	Priority	Order
db-01	100	First
web-01	50	After db-01
web-02	50	After db-01 (tied by target)
web-03	10	Last

Tag Management

Adding Tags

1. Open the target detail page
2. Click Attach Tags
3. Select one or more existing tags from the list
4. Click Attach

New tags must first be created on the Tags page.

Common Tag Patterns

Key	Example Values	Purpose
role	web, api, worker, db	Server role
region	us-east, eu-west	Geographic location
tier	frontend, backend	Application tier
team	platform, payments	Owning team
environment	production, staging	Legacy env tracking

Deleting Targets

Delete

Permanently removes the target:

1. Open target details
2. Click Delete
3. Confirm deletion

Deleted targets:

• Are removed from all environments
• No longer receive deployments

What Happens to the Agent

After target deletion:

• Tarsus agent continues running.
• The agent re-registers on restart. Because the approved client_registration has no FK to the target, it survives the delete, so the agent re-registers as already-approved and the target is recreated immediately — it does not return to pending. Revoke the registration if you want it gone for good.

Monitoring Target Health

Health Dashboard

The dashboard shows overall health:

┌─────────────────────────────────────────────────────────┐
│  Target Health                                          │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐     │
│  │   Online    │  │    Stale    │  │   Offline   │     │
│  │     10      │  │      1      │  │      1      │     │
│  │   (83%)     │  │    (8%)     │  │    (8%)     │     │
│  └─────────────┘  └─────────────┘  └─────────────┘     │
│                                                         │
└─────────────────────────────────────────────────────────┘

Status Transitions

Troubleshooting

Target Shows Offline

1. Check Tarsus agent is running on the machine
2. Verify network connectivity
3. Check firewall rules
4. Review Tarsus logs

Target Shows Stale

• Usually temporary during network issues
• Will return to Online when heartbeat received
• If persistent, investigate network path

Cannot Delete Target

Cause: Insufficient permission (targets:delete) or wrong tenant scope — an active deployment does not block deletion (every FK to targets is ON DELETE CASCADE/SET NULL).

Solution: Use a token with targets:delete scoped to the target’s tenant.

Tags Not Saving

Cause: There is no character/case validation (keys/values are validated only for length 1–255). A save failure is instead a 404 (the tag or target is not adopted by the caller’s tenant) or a 403 (missing targets:update).

Solution: Confirm the tag and target belong to your tenant and that your token has targets:update.

Best Practices

1. Consistent Naming

Use a naming convention:

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

2. Tag Everything

Apply tags systematically for filtering:

role: web
region: us-east-1
team: platform
tier: frontend

3. Regular Health Checks

Monitor target health:

• Review offline targets daily
• Investigate stale targets
• Clean up unused targets

4. Document Environment Assignments

Track which targets belong where:

Target	Development	Staging	Production
web-01	-	-	Priority 1
web-02	-	-	Priority 2
web-staging	-	Priority 1	-
web-dev	Priority 1	-	-

Next Steps

• Listen vs Poll Mode - Connection modes
• Health Status - Understanding target health
• Tagging - Tag strategies
• Overview - Return to targets overview