sp agent

When agents use this: Install a backend-compatible sp-agent.jar and get copy-paste JVM flags after sp app create.

Synopsis

Subcommand	Description
download	Fetch bundled jar from sp-boot; default install dir under XDG data home
command	Emit -javaagent and sp.* system properties for record mode

agent download

sp agent download --json
sp agent download --out-dir "${XDG_DATA_HOME:-$HOME/.local/share}/softprobe/agent" --json

Default install directory: ${XDG_DATA_HOME:-~/.local/share}/softprobe/agent.

Writes:

• sp-agent.jar — verified against backend manifest sha256
• manifest.json — { "version", "sha256", "sizeBytes", "builtAt" }

Re-download is skipped when the on-disk jar already matches the backend manifest.

Example envelope:

{
  "ok": true,
  "command": "agent download",
  "data": {
    "dir": "/home/user/.local/share/softprobe/agent",
    "path": "/home/user/.local/share/softprobe/agent/sp-agent.jar",
    "manifestPath": "/home/user/.local/share/softprobe/agent/manifest.json",
    "version": "3.9.56",
    "sha256": "…",
    "sizeBytes": 27055970,
    "reusedExisting": false
  }
}

agent command

sp agent download --json
sp agent command --app a1b2c3d4e5f67890 --json
sp agent command --app a1b2c3d4e5f67890 --agent-jar /opt/softprobe/sp-agent.jar --app-jar target/app.jar --json

Flag	Description
--app	Required. Registered appId from sp app create
--agent-jar	Optional. Default: $SP_AGENT_JAR, then ${XDG_DATA_HOME}/softprobe/agent/sp-agent.jar
--app-jar	Optional. Trailing -jar … in startCommand
--storage-host	Override -Dsp.storage.service.host=
--config-host	Override -Dsp.config.service.host= (defaults to storage host)
--format	json (default), shell, docker, maven

Host inference from profile URL:

• http://127.0.0.1:8090 → 127.0.0.1:8090
• https://api.example.com → api.example.com (no default port)

When the default jar is missing:

{
  "ok": false,
  "command": "agent command",
  "error": {
    "code": "USAGE",
    "message": "sp-agent.jar not found; run sp agent download",
    "backend": {
      "nextActions": ["sp agent download"]
    }
  }
}

Example success data (abbreviated):

{
  "appId": "a1b2c3d4e5f67890",
  "agentJar": "/home/user/.local/share/softprobe/agent/sp-agent.jar",
  "agentJarExists": true,
  "storageHost": "127.0.0.1:8090",
  "configHost": "127.0.0.1:8090",
  "jvmArgs": [
    "-javaagent:/home/user/.local/share/softprobe/agent/sp-agent.jar",
    "-Dsp.app.id=a1b2c3d4e5f67890",
    "-Dsp.storage.service.host=127.0.0.1:8090",
    "-Dsp.config.service.host=127.0.0.1:8090"
  ],
  "startCommand": "java -javaagent:… -Dsp.app.id=… …",
  "startCommandMultiline": "java \\\n  -javaagent:… \\\n  …",
  "dockerJavaToolOptions": "-javaagent:… …",
  "mavenArgLine": "-javaagent:… …",
  "nextActions": [
    "Run startCommand (or paste startCommandMultiline into a run script)",
    "Send traffic, then: sp record case list --app a1b2c3d4e5f67890 --since -1h --json"
  ]
}

--format	stdout
json	Full envelope on stdout
shell	startCommandMultiline only
docker	ENV JAVA_TOOL_OPTIONS='…'
maven	<argLine>…</argLine>

REST mapping

Subcommand	Method	Path
download	GET	/api/agent/java/manifest
download	GET	/api/agent/java/download

Related

• setup doctor
• app — create app and check heartbeat
• record — list recorded cases
• Concepts: Java agent