# Agent The agent is a native library that is attached to a JVM. Each agent opens a single, bidirectional TCP connection to the Flopsar server and keeps it open until the JVM shuts down. Over that connection the agent receives its instrumentation profile and streams back execution stacks, parameters, exceptions, and JVM metrics. {% hint style="warning" %} Running the Flopsar agent alongside other instrumenting agents is not recommended. If you run into problems, detach the other agents first. {% endhint %} Installing the agent comes down to making the native library available to your JVM and pointing it at the server: 1. Select the agent library for your platform and architecture (see Supported Platforms and Requirements). 2. Copy the library to the machine that runs your Java application. 3. Configure the agent by adding it to your JVM options (see Attaching the Agent and Configuration). 4. Restart your application. The library is a single, self-contained file: * `libflopsar.so` on Linux. * `flopsar.dll` on Windows. No additional files need to be installed; the supporting Java classes are bundled inside the library itself. ## Attaching the Agent The agent is loaded by the JVM at startup. You can attach it in two ways. The first is to add the `-agentpath` option to the `java` command: ``` -agentpath:= ``` For example, `-agentpath:/opt/flopsar/libflopsar.so=opt1,opt2` loads the agent from `/opt/flopsar/libflopsar.so` and passes the options `opt1,opt2` to it. {% hint style="info" %} There are many places where JVM options can be set, depending on the software you use (startup scripts, application server configuration, environment variables, and so on). Refer to your software's documentation for how to add extra JVM options. {% endhint %} The second way is to set the `JAVA_TOOL_OPTIONS` environment variable: ```shellscript $ export JAVA_TOOL_OPTIONS="-agentpath:=" ``` {% hint style="warning" %} `JAVA_TOOL_OPTIONS` is picked up by **every** JVM started in an environment where it is set. Use it deliberately, and prefer per-application JVM options when you want to target a single process. {% endhint %} {% hint style="info" %} The agent attaches during JVM startup. It must be present in the JVM options when the process starts — attaching to an already-running JVM is not supported. {% endhint %} ## Configuration The agent is configured with a comma-separated list of options, each in the form `key=value`, passed right after the library path in the `-agentpath` option. All of the following options are mandatory. * **`app`** — the application name the agent is assigned to. Use the **same** name for every instance of a horizontally scaled service (all running the same application code). * **`server`** — the socket address of the Flopsar server, in the form `host:port`. The agent initiates the connection to this address. * **`key`** — the agent token (a pre-shared key) used to authenticate and encrypt the connection to the server. See Providing the Agent Token below. A complete example: ``` -agentpath:/opt/flopsar/libflopsar.so=app=MyApplication,server=192.168.10.11:9000,key=env:FLOPSAR_PSK ``` This will: * load the agent from `/opt/flopsar/libflopsar.so`; * assign the agent to the application *MyApplication*; * connect to the Flopsar server at `192.168.10.11:9000`; * read the agent token from the `FLOPSAR_PSK` environment variable. ### Providing the Agent Token The `key` option authenticates the agent to the server and secures the connection. Its value selects **where** the token is read from, in the form `variant:value`. A token is a 256-bit key, represented as 64 hexadecimal characters. * **`env:`** — read the token (64 hex characters) from the environment variable ``. For example, `key=env:FLOPSAR_PSK`. * **`file:`** — read the token from a file. The file must contain exactly 64 hexadecimal characters. For example, `key=file:/etc/flopsar/agent.key`. * **`hex:`** — provide the token inline as 64 hexadecimal characters. For example, `key=hex:0123…`. {% hint style="warning" %} Prefer `env:` or `file:` over `hex:`. Command-line arguments are visible to other users and processes on the host (for example, through the process list), so an inline `hex:` token can be exposed. Reserve `hex:` for development and testing. {% endhint %} You generate and manage agent tokens on the server. See \[Agent Tokens]\(/administrator-guide/agent.md#agent-tokens) for how to create a token for an application and roll it over when needed. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.flopsar.com/7/administrator-guide/installation/agent.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.