# Run OBI as a standalone process

> Learn how to setup and run OBI as a standalone Linux process.

---

Site [llms.txt](/pt/llms.txt)

---

OBI can run as a standalone Linux OS process with elevated privileges that can
inspect other running processes.

## Download and verify

OBI provides pre-built binaries for Linux (amd64 and arm64). Download the
archive for your architecture from the
[releases page](https://github.com/open-telemetry/opentelemetry-ebpf-instrumentation/releases/tag/v1.0.0).
Each release includes:

- `obi-v<version>-linux-amd64.tar.gz` - Linux AMD64/x86_64 archive
- `obi-v<version>-linux-arm64.tar.gz` - Linux ARM64 archive
- `obi-v<version>-linux-amd64.cyclonedx.json` - CycloneDX SBOM for the AMD64
  archive
- `obi-v<version>-linux-arm64.cyclonedx.json` - CycloneDX SBOM for the ARM64
  archive
- `obi-v<version>-source-generated.cyclonedx.json` - CycloneDX SBOM for the
  source-generated archive
- `obi-java-agent-v<version>.cyclonedx.json` - CycloneDX SBOM for the embedded
  Java agent and its Java dependencies
- `SHA256SUMS` - Checksums for verification of the release archives and SBOM
  assets

Each archive, SBOM, and `SHA256SUMS` file has a Cosign signature bundle named
`<asset>.bundle.json`.

Container images for the same release are also published. For image pull and
signature verification instructions, see
[Run OBI as a Docker container](../docker/).

Set your desired version and architecture:

```sh
# Set your desired version (find latest at
# https://github.com/open-telemetry/opentelemetry-ebpf-instrumentation/releases)
VERSION=1.0.0

# Determine your architecture
# For Intel/AMD 64-bit: amd64
# For ARM 64-bit: arm64
ARCH=amd64

# Download the archive for your architecture
wget https://github.com/open-telemetry/opentelemetry-ebpf-instrumentation/releases/download/v${VERSION}/obi-v${VERSION}-linux-${ARCH}.tar.gz

# Download checksums
wget https://github.com/open-telemetry/opentelemetry-ebpf-instrumentation/releases/download/v${VERSION}/SHA256SUMS

# Verify the archive
sha256sum -c SHA256SUMS --ignore-missing
```

Successful verification prints an `OK` result for each downloaded file:

```text
obi-v${VERSION}-linux-${ARCH}.tar.gz: OK
```

If verification fails, `sha256sum` reports `FAILED`. When that happens:

- confirm that `VERSION` matches the archive and `SHA256SUMS` you downloaded
- remove any partially downloaded files and fetch them again
- verify only the files you actually downloaded from that release

Download the archive's signature bundle and verify its signature with
[Cosign](https://docs.sigstore.dev/cosign/verifying/verify/):

```sh
wget https://github.com/open-telemetry/opentelemetry-ebpf-instrumentation/releases/download/v${VERSION}/obi-v${VERSION}-linux-${ARCH}.tar.gz.bundle.json

cosign verify-blob obi-v${VERSION}-linux-${ARCH}.tar.gz \
  --bundle obi-v${VERSION}-linux-${ARCH}.tar.gz.bundle.json \
  --certificate-identity "https://github.com/open-telemetry/opentelemetry-ebpf-instrumentation/.github/workflows/release.yml@refs/tags/v${VERSION}" \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com'
```

After signature verification succeeds, extract the archive:

```sh
tar -xzf obi-v${VERSION}-linux-${ARCH}.tar.gz
```

The archive contains:

- `obi` - Main OBI binary
- `LICENSE` - Project license
- `NOTICE` - Legal notices
- `NOTICES/` - Third-party licenses and attributions

> [!IMPORTANT]
>
> Starting in OBI v0.6.0, the Java agent is embedded in the `obi` binary. No
> separate `obi-java-agent.jar` file is required. At runtime, OBI extracts and
> caches the embedded Java agent under `$XDG_CACHE_HOME/obi/java` (or
> `~/.cache/obi/java`).
>
> The cache directory is determined by the user account running `obi`. When you
> use `sudo`, the cache will typically be created under the root user's cache
> directory (for example `/root/.cache/obi/java`) unless you override it. For
> system or service deployments, set `XDG_CACHE_HOME` to a suitable location
> (for example `XDG_CACHE_HOME=/var/cache/obi sudo -E obi ...`) or configure an
> explicit cache path according to your environment.

## SBOMs

CycloneDX SBOM files are optional metadata for supply-chain review and
automation. They are not required to install or run OBI.

The published SBOMs describe the contents of the binary archives and embedded
components in [CycloneDX JSON format](https://cyclonedx.org/). They can be used
with standard SBOM tooling to inspect dependencies, licenses, and components
without executing the binaries.

The v1.0.0 archive SBOMs omit the embedded Java agent's Byte Buddy dependencies
and report the agent version as `UNKNOWN`. To inspect Java dependencies, use the
companion `obi-java-agent-v1.0.0.cyclonedx.json` SBOM and its signature bundle.

Download the SBOMs you want to inspect:

```sh
# SBOM for the binary archive you downloaded
wget https://github.com/open-telemetry/opentelemetry-ebpf-instrumentation/releases/download/v${VERSION}/obi-v${VERSION}-linux-${ARCH}.cyclonedx.json

# SBOM for the embedded Java agent and its Java dependencies
wget https://github.com/open-telemetry/opentelemetry-ebpf-instrumentation/releases/download/v${VERSION}/obi-java-agent-v${VERSION}.cyclonedx.json

# Optional: verify the downloaded SBOM files against SHA256SUMS too
sha256sum -c SHA256SUMS --ignore-missing
```

Example inspection commands:

```sh
# List component names and versions from the archive SBOM
jq '.components[] | {name, version}' obi-v${VERSION}-linux-${ARCH}.cyclonedx.json

# Scan the SBOM with Grype
grype sbom:obi-v${VERSION}-linux-${ARCH}.cyclonedx.json

# Inspect the Java agent dependency graph
jq '.components[] | {name, version}' obi-java-agent-v${VERSION}.cyclonedx.json
```

## Install to system

After extracting the archive, you can install the binaries to a location in your
PATH so they can be used from any directory.

The following example installs to `/usr/local/bin`, which is a standard location
on most Linux distributions. You can install to any other directory in your
PATH:

```bash
# Move binaries to a directory in your PATH
sudo cp obi /usr/local/bin/

# Verify installation
obi --version
```

## Set up OBI

1. Create a configuration file following the
   [configuration options](../../configure/options/) documentation. You can
   start with the [OBI configuration YAML example](../../configure/example/).

2. Run OBI as a privileged process:

   ```bash
   sudo obi --config=<path to config file>
   ```

   If you did not install OBI to your PATH, you can run it from the extracted
   directory:

   ```bash
   sudo ./obi --config=<path to config file>
   ```

## Permissions

OBI requires elevated privileges to function properly. For more information
about the specific capabilities required, see the
[security documentation](../../security/).