Agent Install

The Beam agent is a small background process that watches for OBS output and uploads stream segments to Beam. Most users do not need to run the agent directly — the OBS plugin handles this automatically.

You would install the standalone agent if:

• Your technical team prefers to manage the upload process separately from OBS.
• You are running a configuration where the OBS plugin is not suitable.
• Support has asked you to run the agent for diagnostic purposes.

For the standard setup, follow Getting Started and OBS Plugin Install (macOS) instead.

macOS installation

1. Download the agent binary

Download the latest macOS agent from the Beam dashboard under Settings → Downloads, or from the downloads page.

Choose the right binary for your Mac:

• Apple Silicon (M1, M2, M3, M4): beam-agent-darwin-arm64
• Intel Mac: beam-agent-darwin-amd64

2. Make the binary executable

Open Terminal and run:

chmod +x ~/Downloads/beam-agent-darwin-arm64

Replace darwin-arm64 with darwin-amd64 if you downloaded the Intel version.

You can move the binary to a permanent location, for example:

mv ~/Downloads/beam-agent-darwin-arm64 /usr/local/bin/beam-agent

3. Create the agent config file

The agent reads a YAML config file. Start from the example below:

stream_id: "your-stream-id-here"
agent_id: "primary"
api_endpoint: "https://ingest.beamnetworks.stream"
api_key: "sk-live-your-api-key-here"

hls_watch_dir: "/tmp/obs-hls"
cache_dir: "/tmp/beam-agent-cache"
cache_max_minutes: 30

upload_timeout_seconds: 10
upload_retry_max: 5
upload_retry_backoff_base_ms: 500

backfill_poll_interval_seconds: 2
segment_expected_duration_ms: 2000

log_level: "info"

Save this as agent.yaml in a location of your choice (for example, ~/beam/agent.yaml).

Fill in:

Setting	Where to find it
stream_id	Beam dashboard → Settings → Stream
api_key	Beam dashboard → Settings → API Keys

Do not commit agent.yaml to version control — it contains your API key.

4. Configure OBS to write HLS output

The agent watches a local directory for OBS output. OBS must be configured to write HLS segments to the directory specified in hls_watch_dir (default: /tmp/obs-hls/).

Contact support or see the OBS guide if you need help with this step — OBS must write 2-second HLS segments for the agent to process them correctly.

5. Run the agent

beam-agent --config ~/beam/agent.yaml

The agent will start watching hls_watch_dir and uploading segments as they appear. You should see log output indicating it is running.

To stop the agent, press Ctrl+C in the terminal where it is running.

6. (Optional) Run the agent as a background service

If you want the agent to start automatically and run in the background, you can set it up as a macOS LaunchAgent. Contact support for a sample plist file.

Linux and Windows

Linux and Windows agent support is coming soon. Contact support if you need these platforms before they are documented.

Verifying the agent is working

While the agent is running and OBS is streaming:

1. Check the agent log output in your terminal — you should see messages about segments being detected and uploaded.
2. Check the Beam dashboard — your stream status should show active delivery.

If segments are not being detected, confirm that OBS is actually writing .ts files to the hls_watch_dir directory. See Troubleshooting for more.