Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ultra.security/llms.txt

Use this file to discover all available pages before exploring further.

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:
VariableDescription
ULTRA_DEPLOY_KEYThe deploy key you created
3

Rebuild environments

Rebuild any active Ona environments. On first boot, Ultra auto-links a gateway 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 --client 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"
  ]
}
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 --client 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 server 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 servers 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

# Ona's MCP config points at Ultra
cat /workspaces/.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 --client 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

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: 
ultra install --client ona --yes
ultra migrate --from ona --all --yes
Use this if you added new MCP servers directly to .ona/mcp-config.json and want them pulled into Ultra’s upstream config without rebuilding the environment.