> ## 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.

# Agent Environments

> Run Ultra inside cloud agent dev environments so MCP traffic flows through Ultra automatically

Ultra integrates with [Ona](https://ona.com) 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](/hub/deploy-keys) 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.

<Steps>
  <Step title="Create a deploy key">
    In Ultra Hub, go to **Settings → Security → Deploy Keys** and create a workspace-scoped deploy key. See [Deploy keys](/hub/deploy-keys) for details.
  </Step>

  <Step title="Set environment variables">
    In your Ona organization's environment variables or secrets, add:

    | Variable           | Description                |
    | ------------------ | -------------------------- |
    | `ULTRA_DEPLOY_KEY` | The deploy key you created |
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Quick start

Add a `.devcontainer/devcontainer.json` to your repo (or merge these hooks into an existing one):

```jsonc theme={null}
{
  "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:

```json theme={null}
{
  "mcpServers": {
    "ultra": {
      "command": "/usr/local/bin/ultra",
      "args": ["start"]
    }
  }
}
```

## Verification

After rebuilding, confirm Ultra is wired correctly:

```bash theme={null}
# 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:

```jsonc theme={null}
{
  "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

<AccordionGroup>
  <Accordion title="ultra install prints 'Ona is not installed'">
    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.
  </Accordion>

  <Accordion title=".ona/mcp-config.json created in the wrong directory">
    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`.
  </Accordion>

  <Accordion title="Ona Agent still calls servers directly">
    The Agent reads `.ona/mcp-config.json` at session start. Restart the Agent or open a new Ona session after the devcontainer hooks finish.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Re-running setup manually

Both commands are safe to re-run at any time:

```bash theme={null}
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.