Pod Bridge & Federation

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• CONTEXT.md
• packages/mcp/src/api.ts
• packages/mcp/src/api/interfaces.ts
• packages/api/src/test/productionMigrationChain.test.ts

Pod Bridge & Federation is a coordination layer that establishes federated trust between different Orcy pods. It allows an administrator's pod to safely collaborate in a habitat owned by another pod through provider-backed identity and scoped trust management. This system enables the "Shared Habitat API," remote MCP modes, and grant-based access control for remote participants.

The federation model differentiates between local pod membership and remote pod participation. It ensures that while external agents or humans can contribute to a host habitat, the host pod maintains authoritative control over lifecycle approvals, capabilities, and repository permissions.

Sources: README.md:59-61, CONTEXT.md:27-31

Architectural Overview

The Pod Bridge functions as a transport and governance seam. It allows remote participants (Orcy units or humans from external pods) to interact with a host habitat via a dedicated /api/shared/* surface. This surface enforces mandatory governance interceptors and requires explicit host approval for any capability-bearing tasks.

Multi-Pod Interaction Flow

This diagram illustrates how a remote participant from one pod interacts with a host habitat owned by another pod through the Pod Bridge.

The flow ensures that all remote actions are authenticated via a specific remote key, validated against governance rules, and checked for capability alignment before affecting the habitat state.
Sources: README.md:59-61, packages/mcp/src/api.ts:182-192, README.md:144-148

Identity & Trust Tiers

Orcy defines several levels of participant standing to manage the risk associated with federation. Trust is not binary; it is shaped by the relationship between the participant and the host pod.

Participant Standings

Standing	Description	Authority
Local Member	A member of the pod that owns the habitat.	Full native authority within granted scopes.
Remote Observer	External participant with visibility only.	Can read context and post advisory feedback (comments).
Remote Contributor	External participant with execution rights.	Can claim and submit eligible tasks; no approval authority.
Remote Reviewer	Sits between Observer and Contributor.	Can provide advisory review guidance but cannot approve/reject.
Trusted Remote Pod	Pod-level standing where the host vouches for an entire external pod.	Participants may receive broader baseline scopes by default.

Sources: CONTEXT.md:37-77

Identity Mechanisms

• Provider-Backed Identity: Verification via GitHub, Google, or OIDC presets. It simplifies onboarding but does not grant automatic permissions.
• Remote Orcy Credential: Per-orcy credentials issued for remote work. While a pod-level relationship may bootstrap enrollment, actions are attributed to individual remote orcies.
• Manual Invite Credential: A fallback for establishing trust when third-party provider auth is unavailable.

Sources: CONTEXT.md:42-53, CONTEXT.md:104-108

Remote Operations & Governance

Federated operations are handled through specific API patterns and security constraints designed to prevent unauthorized mutation of the host habitat.

Remote Request Pattern

Remote participants use a specific transport client that targets the /api/shared/ surface. These requests use X-Orcy-Remote-Key instead of the standard X-Agent-API-Key. To ensure reliability over federated networks, write actions are idempotent, utilizing an Idempotency-Key header.

// Example of a remote request structure in the KanbanApiClient
async requestRemote<T>(
  method: string,
  path: string,
  options?: { body?: unknown; idempotencyKey?: string; action?: string; },
): Promise<T> {
  if (!path.startsWith("/api/shared/")) {
    throw new Error("Remote requests must target /api/shared/* endpoints");
  }
  const { remoteKey } = this.getRemoteCredentials();
  const idempotencyKey = options?.idempotencyKey ?? (method !== "GET" ? `mcp-${randomUUID()}` : undefined);
  // ... transport call with X-Orcy-Remote-Key ...
}

Sources: packages/mcp/src/api.ts:182-205

Host-Approved Capabilities

A critical security gate for federation is the Host-Approved Capability. Even if a remote orcy self-declares capabilities (e.g., "Frontend", "Security Audit"), the host habitat must explicitly approve these. If the approvedCapabilities list is empty or does not match the task requirements, the remote claim is refused.
Sources: CONTEXT.md:109-113, README.md:144-148

Lifecycle & Approvals

Federation strictly separates execution from finalization. While remote contributors can move tasks through parts of the lifecycle (Claim -> Start -> Submit), the Lifecycle Approval (Approve/Reject) remains exclusively with local humans or local pod policy.
Sources: CONTEXT.md:95-103

Data Federation & Provenance

When a remote pod collaborates, it contributes to the host habitat's audit trail and evidence collection.

• Remote Evidence Links: Remote contributors provide code evidence as scoped metadata (e.g., Pull Request URLs or Fork branch URLs). This supports provenance without requiring the host to grant broad repository access to the remote pod.
• Audit Attribution: Remote activity is recorded in the audit trail with provenance metadata. It is explicitly distinguished from local activity to ensure that agent quality metrics are not blended unless desired.
• Notification Deduping: The system collapses participants with the same externalIdentityId across pods. This ensures that a single person or orcy collaborating across multiple pods receives only one delivery for a shared event.

Sources: CONTEXT.md:83-94, README.md:139-143

Database Schema for Federation

The system uses dedicated tables to manage remote identities and their interactions.

Table	Purpose
remote_pods	Stores information about federated external pods, including status and trust standing.
remote_webhook_deliveries	Tracks inbound webhooks from remote sources to ensure audit integrity.

Sources: packages/api/src/test/productionMigrationChain.test.ts:241-248, packages/api/src/test/productionMigrationChain.test.ts:466-470

Conclusion

Pod Bridge & Federation enables Orcy to scale beyond a single machine or team by creating a secure, federated environment. By leveraging the Shared Habitat API and Host-Approved Capabilities, it allows for high-trust collaboration while ensuring the hosting pod retains ultimate authority over its task lifecycle and repository integrity.