Docs
Connect an n8n instance
Two ways to read n8n, and the one you should pick. This is the most consequential choice in the setup, so it is made for you here.
Run the agent, unless you need control actions or cannot run a container beside n8n. If that sentence answers your question, go to the agent and come back if something does not fit.
The rest of this page is why.
The two modes
When you connect an instance, Obsevo asks how it should read n8n. The choice determines where your execution data is computed, and whether Obsevo can act on n8n as well as watch it.
| Agent | API key | |
|---|---|---|
| Where execution data is processed | On your host | On Obsevo's servers |
| Network requirement | Outbound HTTPS only | Obsevo must be able to reach your n8n |
| Works behind NAT or a private network | Yes | No |
| Can run control actions | No | Yes |
| Setup | A container beside n8n | Paste a URL and a key |
Agent mode
The agent runs next to n8n, reads it read-only, reduces each execution to metadata locally, and pushes that over outbound HTTPS. It never opens a port and never accepts a callback, so it works from inside a private network with no inbound rule.
This is the mode the privacy claim is about. Execution payloads are never transmitted — only names, statuses, timings, item counts, error text, and for AI nodes the model name, provider and token counts.
API-key mode
You give Obsevo your n8n base URL and an n8n API key, and Obsevo polls the n8n REST API directly. Nothing runs on your side.
Why control actions need API-key mode
The agent is outbound-only by design. It dials out and nothing dials in, which is exactly what makes it safe to run in a private network — and exactly why Obsevo has no route back through it to tell n8n to retry an execution.
So the property that makes agent mode private is the same property that makes it read-only. That is a real trade-off rather than a missing feature, and it is why control actions are only offered on API-key instances.
What you get when you connect
Connecting produces three values:
- an instance ID
- a one-time HMAC secret — shown once, used by the agent to sign its pushes
- the ingest URL — your
ingest.<domain>, or just<domain>on a single-hostname install
Keep the secret somewhere before you close the page. If you lose it, rotate it from the instance's settings rather than creating a second instance — a duplicate instance reporting the same n8n produces duplicate incidents, and Obsevo will warn you when it detects one.
Next
- Install the agent, including how to verify it is working
- Add real-time capture so runs appear in about a second instead of on the next poll
- Set up alert channels — an instance with no channel detects everything and tells nobody