Runtime Targeting

Everything in RayLimit starts with selecting one runtime target. If runtime selection is weak, everything after it becomes weak.

Supported Runtime Selectors

The public CLI supports these runtime selectors:

• --pid <pid>
• --container <id-or-name>
• --name <name>
• optional --source host_process|docker_container

For limit, exactly one runtime must be selected. For inspect, you can also use --all to inspect every matching target.

What Runtime-Local Means

Runtime locality is part of the product contract:

• one runtime plus one subject equals one limiter identity
• another runtime gets a different identity even if the tag or IP string is the same
• observation, reconcile, and cleanup all stay inside that runtime boundary

That matters directly for the IP model. --ip all is always scoped to one selected runtime only. In shared mode it is one runtime-local shared baseline. In per_ip mode it expands only the client IPs currently proven for that runtime. It is not a host-global default and it does not automatically cover other runtimes on the same host.

Selection Rules That Matter In Practice

• inspect can run without selectors and show every discovered target
• limit requires exactly one runtime
• --pid and --container cannot be combined
• --source=docker_container cannot be used with --pid
• --source=host_process cannot be used with --container

If you match multiple runtimes with inspect and do not pass --all, RayLimit stops and asks you to refine the selection instead of choosing one silently.

Common Selection Patterns

Select one host process:

sudo raylimit inspect --pid 1234
sudo raylimit limit --pid 1234 --ip all --device eth0 --direction upload --rate 4096

Select one Docker runtime:

sudo raylimit inspect --source docker_container --container xray-edge
sudo raylimit limit --source docker_container --container xray-edge --outbound proxy-out --device eth0 --direction upload --rate 2048

Select by discovered name:

sudo raylimit inspect --name edge-eu
sudo raylimit limit --name edge-eu --inbound api-in --device eth0 --direction upload --rate 2048

Inspect every runtime from one discovery source:

sudo raylimit inspect --source host_process --all

Binary Detection And Resolution

Before a runtime can be selected, discovery has to recognize it as an Xray-family process or container, then resolve which binary to query.

Prefix-Match Detection

Detection normalizes a binary basename (lowercase, trailing .exe removed) and prefix-matches it against an allowlist:

• xray
• xray-core
• sanaei
• sanaei-core

Because the match is a prefix match, OS/arch release names and fork builds are recognized without extra configuration: xray-linux-amd64, xray-darwin-arm64, sanaei-linux-amd64, and even the 15-character /proc/<pid>/comm truncation (xray-linux-amd6). The Sanaei fork is detected through the sanaei* prefixes; vanilla Xray is detected through xray*.

Docker Detection Signals

For container runtimes, detection combines four signal classes and keeps the highest confidence while retaining every matched reason:

app is matched as a prefix; com.docker.compose.service and org.opencontainers.image.title are matched as substrings.

When running containers are scanned but none match any signal, discovery records a no_matches limitation (it is a limitation, not a fatal error — other discovery sources still return their results).

Binary-Name Resolution Precedence

When RayLimit queries the Xray API, it resolves the binary in this order:

For host runtimes:

1. --xray-binary (or RAYLIMIT_XRAY_BINARY)
2. the detected absolute executable path (HostProcess.ExecutablePath)
3. the detected binary basename (Identity.Binary)
4. the literal "xray" fallback

For container runtimes:

1. --xray-binary (or RAYLIMIT_XRAY_BINARY)
2. the detected in-container binary basename
3. the literal "xray" fallback

Use --xray-binary when the fork binary lives at a non-standard path:

sudo raylimit discover --xray-binary /opt/sanaei/sanaei-linux-amd64

Container CLI Override

Discovery and container queries default to docker. Use --container-cli (or RAYLIMIT_CONTAINER_CLI) to select podman or nerdctl:

sudo raylimit discover --container-cli podman

Why Selection Discipline Matters

If runtime selection is ambiguous:

• the limiter subject changes
• the runtime evidence source changes
• the managed owner identity changes
• the cleanup target changes

For that reason, RayLimit validates runtime selection early instead of continuing with a weak target identity.