Run Defender on a headless Linux host

Install Cortex Defender on Debian 13 or newer, Fedora, or Amazon Linux 2023 to capture supported agents on one host. The commands below use the supplied agent-rs-mitm package and service. For a shared gateway, see Egress Gateway on Kubernetes.

After installation, configure the clients, review and trust the certificate authority (CA) where required, and enroll the host for your organization. You can verify local capture before enrollment. With the enrollment requirement enabled in the configuration below, activity stays on the host until enrollment succeeds.

Before you begin

Install and start the service

1. Obtain the approved package for the host architecture from Chaos Labs. <DEFENDER_VERSION> is the exact version in that package filename. The examples below show x64 filenames; use the actual organization-supplied filename for other architectures.
2. Install the Cortex Defender package with your operating system's package manager:

sudo apt install "./agent-rs-mitm_<DEFENDER_VERSION>-1_amd64.deb"
# or
sudo dnf install "./agent-rs-mitm-<DEFENDER_VERSION>-1.x86_64.rpm"

The package creates an unprivileged agent-rs service account and leaves the service disabled.

3. Start it once to generate the host-specific CA, then check its logs:

sudo systemctl start agent-rs-mitm
sudo journalctl -u agent-rs-mitm -n 50 --no-pager

Configure the local service

4. Create /etc/agent-rs/mitm.env from this deployment example. <CAPTURE_API_URL> is the complete capture-ingestion URL supplied for your organization, not the client Gateway base URL. Replace it with that issued URL:

# Local TLS-intercepting listener for explicitly configured clients.
MITM_LISTEN_ADDR=127.0.0.1:9001

# Loopback relay, status, and capture-inspection API.
PROXY_LISTEN_ADDR=127.0.0.1:9000

# Persistent per-install CA material.
MITM_CA_PATH=/var/lib/agent-rs/ca.pem
MITM_CA_KEY_PATH=/var/lib/agent-rs/ca-key.pem

# Local service and capture state.
CAPTURE_STATE_DB_PATH=/var/lib/agent-rs/agent-state.sqlite
CAPTURE_LOCAL_SQLITE_ENABLED=1
CAPTURE_LOCAL_SQLITE_PATH=/var/lib/agent-rs/exchanges.sqlite
AGENT_USE_OS_KEYSTORE=0

# Managed upload. A nonempty CAPTURE_API_URL enables upload.
AGENT_RS_MITM_MANAGED_ENABLED=1
CAPTURE_API_URL=<CAPTURE_API_URL>
# When set to 1, device events wait for enrollment before managed upload.
CAPTURE_REQUIRE_ENROLLMENT=1

# Headless capture scope.
PROCESS_LINEAGE_ENABLED=0
WORKMEMORY_ROUTER_SHADOW_OBSERVATION_ENABLED=0
GATEWAY_POLICY_ENFORCEMENT_ENABLED=0

# Journald logging and redacted local inspection.
LOG_FORMAT=json
RUST_LOG=info,agent_rs=debug
CAPTURE_INSPECTOR_UNREDACTED=0

Keep both listeners on loopback. The package's systemd unit reads this file as the unprivileged agent-rs user and stores state under /var/lib/agent-rs. Do not place an onboarding token in the file.

5. Restart the service to apply the local configuration:

sudo systemctl restart agent-rs-mitm

You can configure agents and verify local capture before enrollment.

Enroll for managed upload

6. Enroll when your organization requires managed upload. Obtain a current onboarding ID token and pass it to the enrollment command on standard input. Replace the identity placeholders with the organization and identity-provider values supplied during onboarding:

sudo systemctl restart agent-rs-mitm
sudo -v
read -r -s -p "Onboarding token: " CORTEX_ONBOARDING_TOKEN
printf '\n'
printf '%s\n' "$CORTEX_ONBOARDING_TOKEN" | sudo agent-rs-mitm onboard \
  --provider-id <provider-id> \
  --organization-domain <example.com> \
  --client-id <user@example.com>
unset CORTEX_ONBOARDING_TOKEN

For unattended provisioning, pipe the token directly from the approved deployment secret manager. Do not write it to a file or put it on the command line. The token is used once and is not saved. If enrollment fails while CAPTURE_REQUIRE_ENROLLMENT=1, local capture remains available, but activity stays on the host until enrollment succeeds.

Review and trust the CA

7. Review the generated certificate fingerprint before adding it to system trust:

sudo openssl x509 -in /var/lib/agent-rs/ca.pem \
  -noout -fingerprint -sha256
sudo agent-rs-mitm-trust install
sudo agent-rs-mitm-trust status
sudo systemctl enable agent-rs-mitm

Only applications using the TLS-intercepting listener need this CA. Browser-specific certificate stores may require a separate explicit import. Configure only the browser or application being inspected to use 127.0.0.1:9001 as its HTTP and HTTPS proxy.

Configure command-line agents

8. Run cli commands as the Unix user who runs the agents, without sudo. Cortex refuses to configure tools as root.

agent-rs-mitm cli detect
agent-rs-mitm cli configure --all
agent-rs-mitm cli status

--all configures only detected installations. To configure selected tools, name them explicitly:

agent-rs-mitm cli configure claude codex gemini

Choose the supported Linux tool and capture path from the supported AI tools catalog. Run cli detect to discover installed tools and selectors; a catalog entry does not mean that a tool is installed on this host.

Provider-native base URLs use http://127.0.0.1:9000 and do not require CA trust. Cursor CLI has no base-URL setting, so install the Cortex Defender CA before configuring it. Restart existing agent processes after configuration.

Verify local capture

9. Check service and capture health without exposing credentials:

curl --fail --silent http://127.0.0.1:9000/status
sudo journalctl -u agent-rs-mitm -n 50 --no-pager

Then run a configured agent, send a test prompt, and run agent-rs-mitm cli status. Confirm that the tool is configured, its service forwarding state is active, and the provider responds.

Service logs show diagnostic information without request or response bodies. To inspect local captures, use these loopback-only diagnostic commands:

curl --fail --silent http://127.0.0.1:9000/captures/recent/summary
curl --fail --silent http://127.0.0.1:9000/captures/recent
curl --fail --silent \
  http://127.0.0.1:9000/status/captures/<exchange-id>

A provider response verifies local forwarding. A recent capture from the loopback inspection API verifies local capture. Neither result proves that the host uploaded activity to Cortex.

The default CAPTURE_INSPECTOR_UNREDACTED=0 hides local paths, inline media, and content restricted by capture policy in these diagnostic results. Change it only on a controlled host when full captured content is required, then restart the service.

Verify managed upload

10. After enrollment, run another test prompt and confirm that the capture appears under the expected person in a user profile in Cortex Atlas. The matching record verifies that the activity was uploaded and associated with the correct person. Until enrollment succeeds, the configuration above keeps captured activity on the host.

Restore configuration and remove Cortex Defender

Restore every managed tool as the owning Unix user before disabling the relay or uninstalling the package:

agent-rs-mitm cli restore --all

Restart the affected tools and verify they connect directly to their providers. Then remove the trust anchor and package:

sudo agent-rs-mitm-trust remove
sudo dnf remove agent-rs-mitm
# or: sudo apt remove agent-rs-mitm

See local port diagnosis for read-only checks on ports 9000 and 9001. The desktop local port reference also describes browser PAC behavior; headless Linux does not use a desktop PAC service on 19090.

The listener has no client authentication. Do not bind it to 0.0.0.0 or enable non-loopback access. For remote inspection, use an authenticated SSH tunnel instead of exposing the proxy port.

Package removal preserves /var/lib/agent-rs so an upgrade does not silently rotate a previously trusted CA. After confirming that captures and the CA are no longer needed, an administrator may remove that directory through the organization's approved data-removal process.