Skip to content

OpenCode install ​

Install Softprobe Blackbox for OpenCode with the @softprobe/opencode-plugin package. Prefer the copy/paste prompt from Explorer (Quick start); this page is the full reference. That prompt tells the coding agent to complete the config steps directly and to fetch docs or inspect packages/binaries only when stuck.

OpenCode loads plugins in two official ways: npm packages listed in config, or local files under a plugins directory. Softprobe uses the npm path. See OpenCode’s docs:

  • Config — opencode.json / opencode.jsonc, merge order, locations
  • Plugins — npm plugin field, Bun install on startup, local plugin dirs

1. Enable the plugin ​

Merge into your existing OpenCode config (JSON or JSONC). Prefer a project file if present; otherwise use the global config:

ScopeFiles
Project./opencode.json or ./opencode.jsonc
Global~/.config/opencode/opencode.json or ~/.config/opencode/opencode.jsonc

OpenCode merges config sources (later sources override conflicting keys). Keep existing keys; if plugin already exists, append @softprobe/opencode-plugin@latest to that array.

json
{
  "experimental": {
    "openTelemetry": true
  },
  "plugin": ["@softprobe/opencode-plugin@latest"]
}

OpenCode installs npm plugins automatically with Bun at startup (cached under ~/.cache/opencode/node_modules/). Restart OpenCode after changing the config.

2. Credentials ​

Create opencode-softprobe.json in the OpenCode config directory (this is a Softprobe credentials file, not part of the OpenCode schema):

  • Default: $XDG_CONFIG_HOME/opencode (or ~/.config/opencode)
  • Override directory with OPENCODE_CONFIG_DIR
json
{
  "ingestionKey": "<Ingestion Key>",
  "otlp": {
    "tracesEndpoint": "https://explorer-staging.softprobe.ai/api/thelake/v1/traces",
    "protocol": "http/protobuf"
  },
  "resourceAttributes": {
    "deployment.environment.name": "staging"
  }
}
FieldRequiredMeaning
ingestionKeyYesIngestion Key (spk_…) from Explorer Agents → + Connect agent
baseUrlNoOptional score API base. It does not select the trace destination.
otlp.tracesEndpointNoFull OTLP traces URL, used as written. If omitted, Softprobe uses its production endpoint. otlp.endpoint can instead hold a generic OTLP base URL, which gets /v1/traces appended.
otlp.protocolNoThe Softprobe exporter supports http/protobuf.
otlp.headersNoAdditional OTLP request headers; these are not sent to the score API.
resourceAttributesNoOpenTelemetry resource attributes, such as deployment.environment.name: staging
userIdNoOptional end-user id on spans

Server SDK environment variables can configure the same OTLP settings. The Ingestion Key is sent through standard OTLP headers:

bash
export INGESTION_KEY="spk_…"
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://explorer-staging.softprobe.ai/api/thelake/v1/traces"
export OTEL_EXPORTER_OTLP_TRACES_HEADERS="Authorization=Bearer ${INGESTION_KEY}"
export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL="http/protobuf"
export OTEL_RESOURCE_ATTRIBUTES="deployment.environment.name=staging"

Explicit fields in opencode-softprobe.json override environment values; environment values fill fields omitted from the file. Do not commit credentials to source control. The exact OTLP endpoint selects the trace destination. Set SOFTPROBE_BASE_URL only when score writes should go to a non-production API.

3. Verify ​

  1. You restart OpenCode (required so the plugin loads in your interactive session). Restart is a user step — the Connect Agent paste prompt does not ask the coding agent to restart.
  2. Ensure a Session was traced: the install prompt has OpenCode run opencode run "What is 1+2?", or run one real chat turn yourself (with tools if you use them).
  3. In Explorer, open Agents → + Connect agent and Check connection, or browse Sessions for the new Session (range filter defaults to the last 7 days).

Sessions are matched to the Explorer Agent via the Ingestion Key; you do not set an agent name in credentials.

What is traced ​

  • User turns (opencode.turn / agent) with prompt text
  • Model generations with completions, usage, and cost
  • Tool executions with arguments and results
  • Retries, reasoning, compaction events
  • Failed steps and session errors / aborts
  • Sub-agent (task) work nested under the parent turn (same product session id; span parent links to the dispatching task when linkage is unambiguous)

Troubleshooting ​

SymptomCheck
No Sessions appearPlugin listed in opencode.json / opencode.jsonc, experimental.openTelemetry true, you restarted OpenCode, then opencode run "What is 1+2?" or one real chat turn
Auth / ingest errorsingestionKey is current and the OTLP trace endpoint targets the intended environment
Wrong OpenCode config fileEdit the file you already use (opencode.json or opencode.jsonc under project or ~/.config/opencode); see OpenCode config
Wrong Softprobe credentials pathConfirm ~/.config/opencode/opencode-softprobe.json (or OPENCODE_CONFIG_DIR); matching environment values override file values
Partial tracesEnsure the process stays alive long enough to flush; serverless/short-lived hosts may need an explicit flush

Package source: @softprobe/opencode-plugin.

API references ​

Arex · Blackbox · Lisa