Ephemeral Hosts
Some agents run on machines that won’t be around tomorrow: a devcontainer, a Codespace, a cloud VM an agent spins up for a task, a self-hosted runner. A normal Omnodex install keeps its event log on the machine and uploads it with your stream secret, and on a disposable host both are a problem. The log disappears with the box, and the secret shouldn’t be there in the first place.
An ingest source fixes both. The host gets a write-only token and your stream’s public key. Each hook event is encrypted to that key on the host and sent straight to the hosted dashboard at the end of each turn. The host keeps no event log and holds nothing that can read what it sent. Omnodex stores the events without being able to read them either. Only your dashboard, with your stream secret, can.
When to use it
Section titled “When to use it”| Your agent runs on | Use |
|---|---|
| Your own laptop or workstation | A normal install |
| A devcontainer, Codespace, cloud VM, dev server or self-hosted runner | An ingest source, as on this page |
| Cowork’s cloud tasks | A personal Cowork plugin, which carries its own source |
Ingest sources work with Claude Code, Codex, GitHub Copilot, Cursor and Antigravity.
Set it up
Section titled “Set it up”-
Create a source. In the hosted dashboard, open Activity and find Ingest sources. Under Record to, pick the stream the events should go to. Give the source a name that says where it runs, such as development container or release runner, and select Create source.
-
Copy the settings. The dashboard shows the Source ID, the Public key and the Ingest token (shown once). Open All environment settings to copy them all at once:
Terminal window OMNODEX_INGEST_API_BASE=https://api.omnodex.comOMNODEX_INGEST_SOURCE_ID=src_...OMNODEX_INGEST_PUBLIC_KEY=...OMNODEX_INGEST_KEY_ID=...OMNODEX_INGEST_TOKEN=oxi_...The token can’t be shown again, so put it in your host’s secret settings (Codespaces secrets, your CI’s secret store) before you select Done, hide token. The source ID and public key aren’t secret and stay visible in the list.
-
Install on the host. With those variables in the environment:
Terminal window npm install -g omnodexomnodex install --ephemeralThat sets up Claude Code and Codex. Name the agents you want instead, for example
omnodex install --ephemeral claude-code copilot cursor. Hooks go in every project on the host, or only one with--this-project. Nothing asks a question, so it runs fine from a build script. The token is read from the environment and never written to disk. -
Run an agent. Events arrive at the end of each turn, in the stream you picked. The source’s row in Ingest sources changes from No events yet to Last used with a time.
Codex asks you to trust new hooks the first time it runs in a project. Approve them with /hooks, or the Codex hooks won’t run.
Devcontainers and Codespaces
Section titled “Devcontainers and Codespaces”The omnodex repository includes a devcontainer feature that does steps 3 and 4 for you whenever a container is created. Copy the devcontainer/src/omnodex folder into your project as .devcontainer/features/omnodex, then add it to devcontainer.json:
{ "features": { "ghcr.io/devcontainers/features/node:1": {}, "./features/omnodex": { "agents": "claude-code,codex" } }}Set OMNODEX_INGEST_PUBLIC_KEY, OMNODEX_INGEST_SOURCE_ID and OMNODEX_INGEST_TOKEN in the container’s environment; Codespaces secrets work. agents takes any of claude-code, codex, copilot, cursor and antigravity, and version pins the omnodex version (default latest).
The feature installs omnodex when the image builds and sets up capture after the container is created, when secrets are available. Without the settings it does nothing, and a failed setup never stops the container from starting.
Managing sources
Section titled “Managing sources”Each stream lists its sources in Ingest sources, with the source ID, when it was created, when it last sent events, and whether it’s Active or Revoked. Refresh sources reloads the list.
One source per environment. Give each place its own source: one for the devcontainer, another for the release runner. Then the list tells you which one is sending, and you can revoke one without touching the others.
Revoke a source when a host is retired or its token may have leaked: select Revoke, then Revoke source. The token stops working at once. Events it already sent stay in your dashboard. To keep a host recording, create a new source and replace its settings.
Adding another host to a source you already have needs the token, which the dashboard can’t show again. Create a new source instead. Stream public key shows the key to pair with an active source.
New sources can’t be created while the stream’s uploads are paused or its authorization is revoked, while the account is suspended, or on the Free plan. Existing sources can still be revoked.
Settings
Section titled “Settings”| Variable | Notes |
|---|---|
OMNODEX_INGEST_PUBLIC_KEY | Required. Your stream’s public key |
OMNODEX_INGEST_SOURCE_ID | Required. The source’s ID, src_... |
OMNODEX_INGEST_TOKEN | The write-only token. Leave it out only if a proxy in front of the host adds the Authorization header |
OMNODEX_INGEST_KEY_ID | Worked out from the public key when left out |
OMNODEX_INGEST_API_BASE | Defaults to https://api.omnodex.com |
OMNODEX_INGEST_REDACT=1 | Replace tool parameter values with [REDACTED] before they’re encrypted |
OMNODEX_SEALED=0 | Turn capture off on this host without uninstalling |
The non-secret settings can also live in a JSON file, .omnodex/ingest.json in the project or ~/.omnodex/ingest.json, with the fields public_key, source_id, key_id, api_base and redact_parameters. The public key and source ID are safe to commit. The token never is.
Limits
Section titled “Limits”- It records, it doesn’t stop. Hooks on an ingest source never block or hold a call, so shadow mode and guardrails don’t apply there.
- Nothing is kept on the host. There’s no local event log and no local dashboard on that machine. Everything is in the hosted dashboard.
- Events arrive per turn, not per call, so a turn in progress shows up when it ends.
- A capture failure never stops the agent. If the settings are missing or the network is down, the hook answers the agent as usual and the agent carries on.
- Anyone with the token can add events to your stream, though not read any. Treat it like any other secret, and revoke it if it leaks.
Next steps
Section titled “Next steps”- Hosted Dashboard: where the events show up
- Encryption: how events sealed to your public key are protected
- CLI Commands: every
installoption