Skip to main content
Ultra integrates with Ona cloud dev environments so that every MCP call made by the Ona Agent flows through Ultra. Configure a deploy key first; then add the devcontainer so install and migration run automatically with no manual steps inside the container.

​
Linking to your Ultra Hub tenant

The devcontainer hooks (below) get Ultra proxying MCP traffic locally. To send traces and audit events to your Ultra Hub tenant, the environment needs to authenticate.

​
Deploy key

Use a deploy key in Ona’s environment variables—interactive ultra login is not available in Ona cloud dev environments. This path is zero-touch for end users and works well for team and fleet deployments.
1

Create a deploy key

In Ultra Hub, go to Settings → Security → Deploy Keys and create a workspace-scoped deploy key. See Deploy keys for details.
2

Set environment variables

In your Ona organization’s environment variables or secrets, add:
3

Rebuild environments

Rebuild any active Ona environments. On first boot, Ultra auto-links a device for each environment, attributed to the correct user. Traces appear in the Hub without any per-user login step.

​
Quick start

Add a .devcontainer/devcontainer.json to your repo (or merge these hooks into an existing one):
Rebuild your Ona environment. Ultra is now proxying all MCP traffic.

​
What happens on first boot

The postCreateCommand runs once when the environment is built:
  1. Installs the Ultra binary into /usr/local/bin/ultra via the install script.
  2. ultra install --agent ona --yes creates .ona/mcp-config.json (and the .ona/ directory if missing) and adds ultra to mcpServers. Existing entries are preserved.
  3. ultra migrate --from ona --all --yes moves any pre-existing MCP connector entries from .ona/mcp-config.json into Ultra’s upstream config (~/.config/ultra/config.yaml), so the Ona Agent only sees ultra and every tool call routes through it.
The postStartCommand runs on every subsequent environment start. It re-runs migrate to catch any MCP connectors you added to .ona/mcp-config.json between sessions. Both commands are idempotent. After the hooks finish, .ona/mcp-config.json looks like:

​
Verification

After rebuilding, confirm Ultra is wired correctly:
If you configured a deploy key, traces should appear in your Ultra Hub dashboard within about 60 seconds of the Ona Agent making an MCP tool call.

​
Merging with an existing devcontainer

If your repo already has a .devcontainer/devcontainer.json with its own lifecycle hooks, chain the Ultra commands onto the end:
The Ultra binary is self-contained, so order only matters if your setup installs tools Ultra depends on (it doesn’t).

​
Troubleshooting

The Ona detector reports Installed=true only when ONA_WORKSPACE_ID is set or the ona CLI is on PATH. This is always true inside an Ona environment. If you see this error outside an Ona environment, that’s expected.
Ultra walks up from the current working directory looking for an existing .ona/ folder. If none is found, it writes under the current working directory. The devcontainer hooks run from the workspace folder (/workspaces/<repo>), so the file lands at /workspaces/<repo>/.ona/mcp-config.json.
The Agent reads .ona/mcp-config.json at session start. Restart the Agent or open a new Ona session after the devcontainer hooks finish.
Confirm the environment is linked. Run ultra doctor inside the container — it reports link status and identity resolution. If the deploy key isn’t picked up, verify ULTRA_DEPLOY_KEY is set in the Ona environment.

​
Re-running setup manually

Both commands are safe to re-run at any time:
Use this if you added new MCP connectors directly to .ona/mcp-config.json and want them pulled into Ultra’s upstream config without rebuilding the environment.