Core Agent

Some of the languages instrumented by Scout depend on a standalone binary for collecting and reporting data. We call this binary the Core Agent. If the Core Agent is required for your language, the Scout agent library for that language will handle downloading, configuring, and launching the Core Agent automatically. However, you may manually manage the Core Agent through configuration options.

Running Manually

With Docker

Simply run the following:


docker pull scoutapp/scoutapm


docker run -p 6590:6590 --name scoutapm scoutapp/scoutapm

Without Docker

1. Create a directory which your app has permissions to read, write and execute into (for our example we will use: /var/www)

cd /var/www
mkdir scout_apm_core

2. Download and test the core agent:

2.1. cd into the scout_apm_core directory

cd ./scout_apm-core

2.2 Download the core agent tarball

curl --output core-agent-download.tgz

2.3 Unzip the core-agent

tar -xvzf core-agent-download.tgz

2.4 Test that core agent is executable


If everything has run successfully, you should see something similar to the following output:

core agent startup info/output

3. Start the core agent:

./core-agent start --daemonize true

Note: this will not persist past a reboot. We suggest adding the core agent to upstart, systemd, or any other processes manager you may be using.

For additional startup flags, check the in-executable help with ./core-agent start --help

4. Check to see that core agent socket is running:

./core-agent probe

If you are using one of the supported languages (PHP, Python, Elixir, and Node.js), you will have to set the following configuration variables to point to the correct socket (as well as disabling the agent from re-downloading and launching the core agent again):

Downloading the core agent to another directory

By default, the core agent will be downloaded into the /tmp directory.

However due to /tmp being as mounted as not executable, or SELinux configuration, or your umask permissions, you may not be able to execute the core-agent in that directory. To change the directory that Scout downloads to, use the configuration SCOUT_CORE_AGENT_DIR.

Your app must have read, write, and execute permissions for this directory. Read your language’s agent configuration reference for more detail. ## Troubleshooting

Checking if the core agent is executable

In some cases, the core agent won’t be able to execute. You may be presented with an error message that looks similar to: [Scout] Failed to launch core agent - exception core-agent exited with non-zero status. Output: sh: 1: /tmp/scout_apm_core/scout_apm_core-v1.2.9-x86_64-unknown-linux-musl/core-agent: Permission denied

Try following Downloading the core agent to another directory above to see if you are able to execute the core agent in another directory to determine if there is a permissions issue with the default location. If you continue having issues, please reach out to us at ## Available platforms and architectures Builds of the Core Agent are available for these platforms and architectures:

Other languages

The Core Agent API is in our tech preview program.

Want to add tracing but Scout doesn’t support your app’s language? You can instrument just about anything (assuming you can communicate via a Unix Domain Socket) with Scout’s Core Agent API. For information, view the Core Agent API on GitHub.

Pinning The Core Agent

By default, all of our agents pin to latest core-agent version that was available when the change was released (at this time the latest agents are pinned to 1.3.0). In order to update to the latest core-agent, you will need to update your agent as well.

Self Hosting

You can download the core-agent at the following URL:

Note the ending/release, where it’s “scout_apm_core-${core_agent_version}-${core_agent_triple}.tgz”

You will need to have both the core-agent binary as well as the manifest.json.

Once these have been added, you will also need to add the following environment variables:

SCOUT_CORE_AGENT_DIR=/path/to/code/scout_apm_core #(path to where the binary and manifest.json are)

Change Log

Here is the latest relase of the core-agent:

[1.3.0] 2020-09-04