# AI Workspace Config Contract

This contract keeps topology differences in env/config instead of product-code branches.

## URL Classes

- Worker-facing URL: returned to or used by the Codex worker. It must be reachable from the machine that executes Codex.
- Backend-internal URL: used by app backends, Platform Assistant, Hub, Gateway, and service-to-service calls.
- Browser URL: used by user-facing UI.
- Downstream app URL: used by an adapter service to mutate/read its owned app backend.

Do not mix these classes. A URL reachable from the Mac browser is not automatically reachable from a remote Codex worker.

## Current Profiles

`local/remote-worker-relay`:

- Tasker UI: `http://task.local.nodedc`
- Platform Assistant: `http://127.0.0.1:18082`
- Local Hub process: `http://127.0.0.1:18081`
- Default worker-facing Hub relay: `wss://ai-hub.nodedc.ru/api/ai-workspace/hub`
- Default Assistant-to-relay control URL: `https://ai-hub.nodedc.ru`
- Assistant action relay id: `local-dev`
- Assistant action gateway returned to worker: `https://ai-hub.nodedc.ru/api/ai-workspace/hub/v1/assistant-relays/local-dev/actions`
- Ops entitlement adapter: `http://host.docker.internal:4100/api/internal/v1/ai-workspace/entitlements` when deliberately enabled
- Ops Gateway downstream Tasker: `http://task.local.nodedc`
- The deployed AI Hub is allowed only as transport. Launcher, Engine, Ops, Authentik, task manager, and downstream app calls must stay local.
- The remote worker must not call product apps directly. Assistant actions must route back through the local AI Workspace Assistant.

`synology/prod-public`:

- Browser Launcher: `https://hub.nodedc.ru`
- Browser Ops: `https://ops.nodedc.ru`
- Worker-facing Hub: `wss://ai-hub.nodedc.ru/api/ai-workspace/hub`
- Platform Assistant internal: `http://ai-workspace-assistant:18082`
- Platform to Ops entitlement: `http://172.22.0.222:18190/api/internal/v1/ai-workspace/entitlements`
- Ops Gateway worker-facing MCP: `https://ops-agents.nodedc.ru/mcp`
- Ops Gateway downstream Tasker: `http://172.22.0.222:18090`
- This is the preferred controlled runtime e2e target.

`tailscale/tunnel-local-e2e`:

- Allowed only as an explicit profile.
- All worker-facing URLs must be reachable from the executing Codex worker through Tailscale or a named tunnel.
- No product code should auto-fallback from localhost to Tailscale to public domains.

## Required Rule

New apps must join AI Workspace through app manifests/config/adapters:

- app id and surface id;
- context schema;
- entitlement adapter URL/token;
- MCP/tool pack URL and worker-facing public URL;
- smoke test contract;
- owner repo/service.

Do not add app-specific address logic to the agent installer, Engine, Ops, or Platform Assistant runtime flow.

## Verification

Before changing worker, Assistant, Hub, or app adapter routing, run:

```sh
sh infra/scripts/check-local-test-system.sh
```

For a live local remote-worker test, require the relay topology explicitly:

```sh
REQUIRE_REMOTE_WORKER_RELAY=1 sh infra/scripts/check-local-test-system.sh
```

Security audit and test matrix:

```text
docs/AI_WORKSPACE_SECURITY_AUDIT_2026-06-20.md
docs/AI_WORKSPACE_TEST_MATRIX.md
```