Holonia — NearBridge

NearBridge is Holonia's first runnable foundation: a native iPhone-to-Mac capability path where discovery stays untrusted, people approve identity, the Mac Host controls which model may run, and the iPhone receives a signed, correlated result.

Watch the 2:50 physical-device demo · Reviewer runbook · Validation evidence

Built for OpenAI Build Week 2026 with Codex and GPT-5.6.

Experimental checkpoint: one real iPhone/Mac pair has completed the Build Week happy path. NearBridge is not production-ready and does not claim payload encryption, concurrent multi-client routing, or arbitrary Agent execution.

1. The Holonia vision
2. How NearBridge fits into Holonia
3. Problem and motivation
4. Why NearBridge comes first
5. 30-second demo flow
6. Architecture and trust boundaries
7. How Codex and GPT-5.6 are used
8. Quick start and tests
9. Physical evidence
10. Current limitations
11. Roadmap
12. NearBridge documentation
13. Licensing

Holonia is a capability-discovery and work-connection network for people, Agents, and organizations. It starts from one question:

When a person or Agent lacks a capability, how can the request find a better Holon, establish trusted contact, delegate bounded work, and receive a verifiable result?

The motivating cases range from a phone reaching a stronger nearby model to a non-technical user finding an Agent, expert, or organization able to complete a task. Those cases share a request → discovery → trust → delegation → result shape, but they do not share one trust domain. Holonia therefore separates a small common Core from local capability paths and future specialized networks.

The governing principle is:

Holon proposes. Host enforces. Human authorizes.

• A Holon is an addressable actor that can respond, act, and deliver.
• A Primary Holon Account owns stable identity, relationships, reputation, and history.
• A Primary Holon Implementation is replaceable software that serves that account.
• A Holonia Host owns identity keys, permissions, network access, policy, audit, and high-risk execution.
• Holonia Core will define the smallest reusable identity, request, response, propagation, and private-session semantics.
• Specialized Networks can later define domain-specific matching, acceptance, payment, reputation, and compliance rules.

The broader Holonia design remains intentionally unfrozen. NearBridge is the concrete, working implementation developed in this repository.

flowchart TD
    Holonia["Holonia<br/>Capability discovery · trusted contact · delegation · delivery · acceptance"]
    NearBridge["NearBridge<br/>Holonia's first runnable foundation"]
    Holonia --> NearBridge

    subgraph Implemented["IMPLEMENTED IN NEARBRIDGE"]
        Discovery["Local discovery<br/>and device trust"]
        Messages["Authenticated messages<br/>and contact workflows"]
        Interfaces["General capability<br/>and adapter interfaces"]
        Results["Bounded model execution<br/>and auditable results"]
    end

    NearBridge --> Discovery
    NearBridge --> Messages
    NearBridge --> Interfaces
    NearBridge --> Results

    subgraph Future["NEXT / LATER"]
        ThirdParty["Signed third-party<br/>Holon adapters"]
        Context["Controlled read-only<br/>project context"]
        Agents["Approval-gated<br/>tool-using Agents"]
        Core["Holonia Core · propagation<br/>private sessions · specialized networks"]
    end

    NearBridge -.-> ThirdParty
    NearBridge -.-> Context
    NearBridge -.-> Agents
    Holonia -.-> Core

Solid lines are implemented by the current NearBridge checkpoint. Dashed lines are planned layers and are not current capability claims. For the more detailed account, implementation, proposal, and Host authority model, see Holonia role and authority details.

The phone in a person's hand is not always the best place to run the strongest available model. Turning a personal Mac into a generic remote-execution server, however, would give a nearby request far too much authority. Nearby discovery also does not prove identity, consent, or what capability will execute.

The missing piece is not merely model access. It is a path that can find a capability without confusing proximity with trust, let a person approve the relationship, constrain what the remote capability can do, and return evidence that the result belongs to the approved request and session.

NearBridge addresses that first local boundary. It lets an iPhone and a user-launched Mac app:

1. discover one another on the same local network without treating discovery as trust;
2. compare and approve a six-digit pairing code on both devices;
3. establish a fresh authenticated session for signed, expiring, replay-aware messages;
4. complete a signed capability-contact workflow;
5. invoke one Host-registered inert-text capability through the Mac-selected Primary Holon adapter; and
6. return a signed typed result, acknowledgement, execution receipt, and sanitized diagnostics.

NearBridge is not the complete Holonia network. It does not implement open P2P propagation, cross-principal reputation, payment, industry rules, or arbitrary remote tools.

With both apps installed, Local Network permission granted, and the Mac's allowlisted Primary Holon selected:

1. launch the iPhone and Mac apps on the same Wi-Fi;
2. select the discovered peer, choose Pair, and approve the same six-digit code on both devices;
3. on the iPhone, choose Request Primary Holon contact and complete the signed contact workflow;
4. enter an ordinary non-sensitive question and choose Ask selected Mac Primary Holon; and
5. observe the bounded answer on both devices together with a signed result, acknowledgement, and correlated execution evidence.

Under that visible flow, the request follows this path:

iPhone question
→ authenticated signed NearBridge invocation
→ Mac Host policy + capability registry
→ user-selected OpenAI model-only Primary Holon
→ fixed GPT-5.6 Responses API request
→ bounded answer
→ signed typed result
→ iPhone validation, display, and acknowledgement

flowchart LR
    subgraph Phone["iPhone app"]
        UI["Question and result UI"]
        PhoneSession["Pairing + fresh authenticated session"]
        Verify["Signature, expiry, correlation, acknowledgement"]
    end

    subgraph Mac["Mac Host app"]
        Discovery["Bonjour discovery<br/>untrusted metadata"]
        HostPolicy["Identity, trust store, session policy"]
        Registry["HolonManifest + capability registry"]
        Selection["User-selected Primary Holon adapter"]
        Receipt["Signed result + execution receipt"]
    end

    subgraph Runners["Narrow execution boundaries"]
        Local["Local-model XPC<br/>no file, command, or network interface"]
        OpenAI["OpenAI model-only XPC<br/>fixed HTTPS endpoint; no tools"]
    end

    UI --> PhoneSession
    PhoneSession <-->|"Network.framework TCP on local Wi-Fi"| HostPolicy
    Discovery -. "discovery is not authentication" .-> PhoneSession
    HostPolicy --> Registry --> Selection
    Selection --> Local
    Selection --> OpenAI
    Local --> Receipt
    OpenAI --> Receipt
    Receipt --> Verify --> UI

NearBridge was created during OpenAI Build Week; the first repository commit is dated 2026-07-17. The demonstrated product path and the development workflow use OpenAI technology in different ways:

Where this is implemented:

• NearBridgeOpenAIRunner.swift defines the bounded model-only request contract.
• OpenAIRunnerService.swift implements the isolated network runner.
• NearBridgeHolonManifest.swift defines versioned manifests and execution profiles.
• NearBridgeOpenAIRunnerTests.swift covers endpoint, model, redirect, body, response, and error boundaries.
• Submission narrative describes the complete Build Week use of GPT-5.6 and Codex.

• macOS 14 or newer with Xcode;
• a physical iPhone running iOS 17 or newer;
• an Apple Development team for device installation;
• both apps active on the same Wi-Fi with Local Network permission; and
• optionally, the reviewer's own OpenAI API key for the real GPT-5.6 path.

cd NearBridge
swift test

1. Open NearBridge/NearBridge.xcodeproj.
2. Run NearBridgeMac on the Mac.
3. Run NearBridgeIOS on the physical iPhone.
4. Follow the three-minute reviewer runbook.

The deterministic and Apple adapters exercise the local trust and capability path without an OpenAI credential. To reproduce the GPT-5.6 path, enter an OpenAI API key in the Mac app; the credential remains in Mac Keychain and is not exposed to the iPhone or sanitized diagnostic export.

At the Build Week review checkpoint:

• 54/54 shared Swift tests passed;
• both macOS and generic iOS Device targets built;
• the Mac bundle embedded both XPC services; and
• one real iPhone/Mac pair showed discovery, explicit pairing, authentication, contact, a real model answer, signed delivery, acknowledgement, correlated receipts, and sanitized export.

See the English validation evidence, reviewer runbook, and evaluation plan.

• NearBridge currently permits one active TCP/authenticated session and one in-flight Primary Holon invocation.
• It does not claim end-to-end payload encryption; the current demo accepts only ordinary non-sensitive text.
• Physical validation covers one iPhone/Mac pair. Concurrent multi-client, network-switching, longevity, simulator, and complete error matrices remain pending.
• Provider selection is limited to compile-time allowlisted adapters; signed third-party adapter admission is not implemented.
• No current capability receives files, workspace access, shell commands, Git, arbitrary URLs, dynamic tools, device control, or a persistent Agent loop.
• Open P2P propagation, reputation, payment, specialized-network rules, and answerer routing belong to later Holonia phases.

The next platform checkpoint is signed third-party adapter admission, version compatibility, and isolation verification. Later work may add:

• multi-client sessions, queues, routing, and explicit answerer selection;
• payload-encryption and recovery decisions;
• a controlled read-only workspace selector and file broker;
• typed, approval-gated tools inside recoverable worktrees; and
• eventually, durable tool-using Agents with budgets, cancellation, audit, and lifecycle recovery.

Open P2P propagation, reputation, payment, and specialized work networks belong to later Holonia phases, not the current NearBridge checkpoint.

• Build Week reviewer runbook
• NearBridge validation evidence
• Build Week evaluation plan
• Build Week submission narrative

The implementation under NearBridge/ is available under the MIT License. That license does not currently apply to the broader Holonia concepts, design documents, roadmaps, media, or project identity. See the repository licensing notice for the exact scope.