# How holaOS Handles Privacy: macOS Permissions and SSRF Protection

> Discover how holaOS prioritizes privacy with robust macOS permissions management and advanced SSRF protection, safeguarding your data at both system and network levels.

- Repository: [holaboss.ai/holaOS](https://github.com/holaboss-ai/holaOS)
- Tags: deep-dive
- Published: 2026-08-15

---

**holaOS protects user privacy through a dual-layer approach: macOS system-level permission handling via the `open_macos_settings` tool and network-level SSRF protection through `ssrfSafeFetch` validation that blocks private IP ranges.**

The holaboss-ai/holaOS repository implements a comprehensive privacy model designed for secure AI agent operations. Understanding how holaOS handles privacy reveals two distinct security layers: operating system permission management for macOS and server-side request forgery (SSRF) prevention for all external network communications.

## macOS System-Level Permission Management

### The open_macos_settings Tool Implementation

In [`runtime/api-server/src/runtime-agent-tools.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/api-server/src/runtime-agent-tools.ts) (lines 6035-6082), the `openMacosSettings` function provides the runtime interface for macOS privacy controls. When an agent encounters a permission failure for Screen Recording, Accessibility, or Full Disk Access, it invokes this tool to open the specific *System Settings → Privacy & Security* pane.

The implementation first attempts to **register Holaboss with macOS** through the desktop bridge, triggering the native permission prompt. When successful, the system displays the standard macOS dialog requesting user consent for the specific capability.

### Desktop Bridge Integration and Fallback Logic

The tool implements a two-tier execution strategy to ensure reliability:

1. **Primary path**: Uses the desktop bridge (Electron main process) to call `POST /api/v1/macos-permission`
2. **Fallback path**: Invokes the host `open` command with `x-apple.systempreferences:com.apple.preference.security?{anchor}` URLs

If the desktop bridge is unavailable, the tool automatically falls back to the host command method, ensuring agents can always guide users to the correct privacy settings regardless of the runtime environment.

## Network Request Privacy and SSRF Protection

### URL Validation with assertPublicHttpUrl

The [`runtime/api-server/src/ssrf-guard.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/api-server/src/ssrf-guard.ts) file (lines 5-15, 29-65, 88-102, 115-165) contains the core protection logic. The `assertPublicHttpUrl` function resolves DNS hosts and validates that no address falls into restricted ranges:

- **Private ranges**: `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`
- **Loopback**: `127.0.0.1`, `::1`
- **Link-local**: `169.254.0.0/16` (including cloud metadata endpoints like `169.254.169.254`)
- **Unique-local**: IPv6 unique-local addresses

The `isBlockedIpLiteral` helper performs these checks before any network connection is established.

### Automatic Enforcement in External Fetches

Every external HTTP(S) request routes through `ssrfSafeFetch`, which automatically applies the validation. The `downloadUrl` tool in [`runtime/api-server/src/workspace-download-url.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/api-server/src/workspace-download-url.ts) demonstrates this integration in production use.

Unless explicitly whitelisted via the `SANDBOX_SSRF_ALLOW_HOSTS` environment variable, any URL resolving to a non-public address is rejected with a `400` error: **url resolves to a non-public address**.

## Practical Implementation Examples

### Requesting macOS Screen Recording Permission

```typescript
// Agent requests macOS Screen Recording access
await agent.callTool("open_macos_settings", { pane: "screen_recording" });

```

When the desktop bridge is present, the response confirms:

```json
{
  "opened": true,
  "via": "desktop",
  "message": "Requested the macOS 'screen recording' permission …"
}

```

If the bridge is unavailable, the response indicates `"via": "host"` while still successfully opening the settings pane.

### Downloading Resources with Built-in SSRF Protection

```typescript
// Safe download automatically validated against private ranges
await agent.callTool("download_url", {
  url: "https://example.com/image.png",
  workspaceId: "ws_123"
});

```

Behind the scenes, `downloadUrl` calls `ssrfSafeFetch`, which validates the URL format, resolves DNS, checks against blocked IP literals, and performs the fetch with manual redirect handling.

### Configuring SSRF Allowlists for Internal Services

```bash

# Allow specific internal host:port combinations

export SANDBOX_SSRF_ALLOW_HOSTS="my.internal.service:8080,build-server.local:3000"

```

Running holaOS with this environment variable permits agents to access specific internal services while maintaining protection against unauthorized network probing.

## Summary

- **macOS permission handling** is implemented in [`runtime/api-server/src/runtime-agent-tools.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/api-server/src/runtime-agent-tools.ts) through the `openMacosSettings` tool, which bridges to the Electron main process or falls back to host commands.
- **SSRF protection** is enforced globally via `ssrfSafeFetch` in [`ssrf-guard.ts`](https://github.com/holaboss-ai/holaOS/blob/main/ssrf-guard.ts), blocking all private, loopback, and metadata IP ranges before connection establishment.
- **Network privacy** applies automatically to every external fetch including the `downloadUrl` tool, unless hosts are explicitly whitelisted via `SANDBOX_SSRF_ALLOW_HOSTS`.
- **Capability declaration** in [`runtime/harnesses/src/runtime-capability-tools.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/harnesses/src/runtime-capability-tools.ts) (lines 830-834) documents the privacy tools available to agents.

## Frequently Asked Questions

### How does holaOS request macOS permissions when an agent operation fails?

When an agent attempts a privileged operation like `screencapture` and encounters a permission error, it invokes the `open_macos_settings` tool with the specific pane name (e.g., `screen_recording`, `accessibility`). The tool attempts to register Holaboss with macOS through the desktop bridge to trigger the native permission prompt, or falls back to opening the system preferences URL directly.

### What specific SSRF protection does holaOS implement?

According to the [`ssrf-guard.ts`](https://github.com/holaboss-ai/holaOS/blob/main/ssrf-guard.ts) source code, holaOS validates every external URL using `assertPublicHttpUrl`, which resolves DNS and blocks addresses in private ranges (`10.x`, `172.16.x`, `192.168.x`), loopback (`127.0.0.1`), link-local (`169.254.x`), and unique-local IPv6 ranges. This prevents agents from accessing internal services or cloud metadata endpoints like `169.254.169.254`.

### Can I allow holaOS agents to access internal network addresses?

Yes, set the `SANDBOX_SSRF_ALLOW_HOSTS` environment variable with comma-separated `host:port` combinations before starting the runtime. This whitelist bypasses the SSRF guard for specific internal addresses while maintaining protection for all other non-public ranges.

### Where is the privacy capability defined in the holaOS codebase?

The privacy capability schema is declared in [`runtime/harnesses/src/runtime-capability-tools.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/harnesses/src/runtime-capability-tools.ts) (lines 830-834), where the `open_macos_settings` tool is categorized under the macOS permissions group. This schema informs agents that they should invoke this tool whenever an operation fails due to missing OS-level permissions.