Agent Environments

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, because 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.

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.

Set environment variables

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

Variable	Description
`ULTRA_DEPLOY_KEY`	The deploy key you created

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):

{
  "postCreateCommand": [
    "bash", "-lc",
    "curl -sSL https://get.ultra.security/install.sh | bash && ultra install --agent ona --yes && { ultra migrate --from ona --all --yes 2>/dev/null || true; }"
  ],
  "postStartCommand": [
    "bash", "-lc",
    "ultra migrate --from ona --all --yes 2>/dev/null || true"
  ]
}

For environments that must authenticate install.sh before execution, use the verified install flow in the devcontainer hook. 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:

Installs the Ultra binary into /usr/local/bin/ultra via the install script.
ultra install --agent ona --yes writes the repository-local .ona/mcp-config.json (typically /workspaces/<repo>/.ona/mcp-config.json), creating the .ona/ directory if missing, and adds ultra to mcpServers. Existing entries are preserved. This holds even when Ona’s devcontainer lifecycle runs before ONA_WORKSPACE_ID is set, because an explicit install falls back to the enclosing Git repository.
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:

{
  "mcpServers": {
    "ultra": {
      "command": "/usr/local/bin/ultra",
      "args": ["start"]
    }
  }
}

Verification

After rebuilding, confirm Ultra is wired correctly:

# Ultra binary is installed
ultra version

# From anywhere inside the repository, Ona's MCP config points at Ultra
repo_root="$(git rev-parse --show-toplevel)" &&
  cat "$repo_root/.ona/mcp-config.json"

# Run diagnostics
ultra doctor -v

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:

{
  "postCreateCommand": [
    "bash", "-lc",
    "<your existing setup> && curl -sSL https://get.ultra.security/install.sh | bash && ultra install --agent ona --yes && { ultra migrate --from ona --all --yes 2>/dev/null || true; }"
  ]
}

The Ultra binary is self-contained, so order only matters if your setup installs tools Ultra depends on (it doesn’t).

Troubleshooting

ultra install warns 'Ona was not detected on this machine'

The Ona detector reports Installed=true only when ONA_WORKSPACE_ID is set or the ona CLI is on PATH. Ona’s devcontainer lifecycle can run before that signal is set, so this warning can appear inside an Ona environment as well as outside one.It is a warning, not a failure. An explicit ultra install --agent ona treats the agent you named as authoritative: it prints the path it is about to configure and continues. The only thing that stops an explicit Ona install is failing to resolve that config path, covered in the next entry.

.ona/mcp-config.json was not created

Ultra writes the repository-root file Ona reads (/workspaces/<repo>/.ona/mcp-config.json on a default Ona VM), never a file under the process working directory or at the filesystem root.An explicit ultra install --agent ona can create the file even when Ona’s lifecycle does not set ONA_WORKSPACE_ID, provided it runs inside the repository you want configured. It writes to the enclosing Git root, so any subdirectory of that repository works.Other operations stay reuse-only outside an Ona environment. Passive detection, drift checks, ultra migrate, and cleanup reuse an existing .ona/mcp-config.json but never create one, so create the file in the repository first if you are relying on those.

ultra install --agent ona exits with 'could not resolve Ona config path'

Ultra tries several roots in order and only reports this when every one fails. It first reuses an existing .ona/mcp-config.json found by walking up from the working directory, then takes the enclosing Git root, and only then looks under /workspaces.Run the command from inside the repository you want configured, with a .git directory at its root. Because the enclosing Git root is chosen before the /workspaces scan, several repositories under /workspaces are harmless as long as you run the command inside the intended one.The /workspaces scan decides the target only when no Git root is found above the working directory. It needs exactly one candidate, so it resolves when /workspaces holds a single unambiguous repository and fails when it holds several.

Ona Agent still calls connectors directly

The Agent reads .ona/mcp-config.json at the start of each execution. Open a new conversation (or start a new Agent execution) after the devcontainer hooks finish. A full VM rebuild is not required.

Traces visible locally but not in the Hub

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:

ultra install --agent ona --yes
ultra migrate --from ona --all --yes

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.

Getting Started

Ultra Hub

Observability

Concepts

Agent Environments

Linking to your Ultra Hub tenant

Deploy key

Quick start

What happens on first boot

Verification

Merging with an existing devcontainer

Troubleshooting

Re-running setup manually

​Linking to your Ultra Hub tenant

​Deploy key

​Quick start

​What happens on first boot

​Verification

​Merging with an existing devcontainer

​Troubleshooting

​Re-running setup manually

Linking to your Ultra Hub tenant

Deploy key

Quick start

What happens on first boot

Verification

Merging with an existing devcontainer

Troubleshooting

Re-running setup manually