Capability Model

1. Status

This document is the source of truth for the OrbitMesh product and domain model.

OrbitMesh is moving from the early Gateway + ingress/egress + sing-box model to:

Node
  -> Edge Runtime
  -> Capability Binding
  -> Runtime Binding
  -> Endpoint

This is a breaking model upgrade. Do not preserve old product semantics through compatibility aliases, fallback code paths, or legacy field interpretation. Database changes must be handled with explicit SQL migrations. Application code should target the new model directly.

2. Product Positioning

OrbitMesh is a one-stop network infrastructure control plane.

It is not a sing-box panel and not a traditional subscription airport system. OrbitMesh controls, deploys, configures, and observes multiple network runtimes across user-owned hosts, recommended VPS hosts, and managed nodes.

Core value:

• unified control plane.
• unified node runtime.
• unified capability abstraction.
• unified runtime plugin model.
• unified desired state orchestration.

3. Core Layers

Capability Layer
  Traffic / Mesh / Gateway / Tunnel

Control Plane
  Tenant, User, Node, Capability, Runtime, Endpoint, Desired State

Edge Runtime
  orbitmesh CLI and orbitmeshd daemon on each node

Runtime Plugin
  sing-box, Xray, EasyTier, Traefik, frp, NGINX, Envoy, WireGuard, ...

4. Domain Objects

4.1 Node

A Node is a host joined to OrbitMesh.

Examples:

• NAS.
• OpenWrt router.
• Mac mini.
• Linux server.
• home broadband host.
• company server.
• self-purchased VPS.
• platform recommended VPS.
• managed node.

A Node is not a Gateway. A Node can enable zero, one, or multiple capabilities and can run multiple runtime bindings.

4.2 Edge Runtime

Edge Runtime is the local OrbitMesh agent on a Node.

Runtime components:

• orbitmesh: user-facing CLI.
• orbitmeshd: long-running daemon.

Responsibilities:

• node enrollment.
• local identity.
• desired state pull.
• runtime installation.
• runtime configuration rendering.
• runtime process management.
• health reporting.
• metrics and usage reporting.
• certificate materialization.
• reconcile local actual state to Control Plane desired state.

Edge Runtime must not own product business logic. It executes desired state.

4.3 Capability

Capability is a product-level network ability exposed by OrbitMesh.

Current core capabilities:

4.4 Capability Binding

A Capability Binding enables a capability role on a Node.

Examples:

node: tencent-hk
capability: traffic
role: traffic.entry

node: aws-test
capability: traffic
role: traffic.exit

node: home-nas
capability: mesh
role: mesh.node

node: home-nas
capability: tunnel
role: tunnel.endpoint

Capability Binding is the correct place for roles such as traffic.entry, traffic.exit, mesh.relay, gateway.http, or tunnel.endpoint.

4.5 Runtime Binding

A Runtime Binding declares that a Node runs a concrete runtime plugin.

Examples:

node: tencent-hk
runtime: sing-box
supports:
  - traffic.entry
  - traffic.exit

node: home-nas
runtime: easytier
supports:
  - mesh.node
  - tunnel.endpoint

A Runtime Binding is implementation-level state. It is not a product capability by itself.

4.6 Endpoint

An Endpoint is a reachable address exposed by a capability binding.

Endpoint examples:

• traffic subscription endpoint.
• Trojan entry endpoint.
• Gateway HTTP endpoint.
• Gateway TCP endpoint.
• Tunnel public endpoint.
• Mesh private address.

Endpoint owns address-level concerns:

• domain.
• DNS record.
• IP or mesh address.
• port.
• protocol.
• certificate binding.
• readiness.
• reachability.

4.7 Desired State

Control Plane converts user intent into desired state. Edge Runtime reconciles local actual state to desired state.

Desired state should reference:

• node.
• capability bindings.
• runtime bindings.
• endpoints.
• runtime configuration manifests.
• certificates and secrets by reference.

Control Plane does not run runtime processes or forward user traffic.

5. Capability Definitions

5.1 Traffic

Traffic handles proxy protocols, outbound access, subscription distribution, and intelligent routing.

Roles:

• traffic.entry: client-facing access role.
• traffic.exit: outbound role toward target services.
• traffic.relay: intermediate traffic relay.
• traffic.subscription: subscription distribution role.
• traffic.route: policy routing role.

Typical scenarios:

• GitHub traffic exits through Tokyo.
• Claude or OpenAI traffic exits through the United States.
• Docker, npm, PyPI use selected exits.
• users receive Clash, Surge, Shadowrocket, sing-box, or custom subscription outputs.
• multiple entry and exit nodes form a traffic path.

Traffic runtimes:

• sing-box.
• xray.
• trojan.
• hysteria.
• shadowsocks.

Entry, Exit, and Relay are Traffic roles. They are not top-level product resources and not software names.

5.2 Mesh

Mesh handles device networking, private network membership, P2P, NAT traversal, relay, and subnet routing.

Roles:

• mesh.node.
• mesh.peer.
• mesh.relay.
• mesh.bridge.
• mesh.subnet_router.
• mesh.exit_node.
• mesh.nat_traversal.

Typical scenarios:

• home NAS joins a private network.
• office devices interconnect.
• multiple VPS instances form a private network.
• home broadband nodes join OrbitMesh without fixed public IPs.

Mesh runtimes:

• easytier.
• tailscale.
• netbird.
• wireguard.
• zerotier.

5.3 Gateway

Gateway handles HTTP/TCP/UDP ingress, reverse proxy, TLS termination, routing, and load balancing.

Roles:

• gateway.http.
• gateway.tcp.
• gateway.udp.
• gateway.tls.
• gateway.load_balancer.

Typical scenarios:

• expose web services.
• route domains.
• terminate HTTPS.
• proxy TCP services.
• provide a unified entry for internal services.

Gateway runtimes:

• traefik.
• nginx.
• envoy.
• haproxy.
• caddy.

Gateway does not mean every OrbitMesh node. It is one capability.

5.4 Tunnel

Tunnel handles intranet penetration and exposing private services to public endpoints.

Roles:

• tunnel.endpoint.
• tunnel.relay.
• tunnel.http.
• tunnel.tcp.
• tunnel.udp.
• tunnel.temporary_share.

Typical scenarios:

• home NAS has no public IP but needs external access.
• local development service is temporarily exposed.
• internal enterprise service is exposed to remote users.
• public domain binds to private service through relay.

Tunnel runtimes:

• frp.
• cloudflare-tunnel.
• ngrok-like-runtime.
• easytier.
• self-hosted tunnel runtime.

Tunnel overlaps with Gateway at the endpoint layer, but the product goal is different. Gateway focuses on service entry and routing. Tunnel focuses on making private services reachable from outside.

6. Runtime Classification

7. Runtime Plugin Contract

Each runtime plugin declares metadata:

runtime: sing-box
display_name: sing-box
primary_capability: traffic
supported_capabilities:
  - traffic
supported_roles:
  - traffic.entry
  - traffic.exit
  - traffic.relay
  - traffic.subscription
  - traffic.route
features:
  - tcp_proxy
  - udp_proxy
  - dns
  - route
  - outbound_chain
protocols:
  - trojan
  - shadowsocks
  - hysteria2

Plugin behavior:

• install.
• configure.
• start.
• stop.
• restart.
• reload.
• upgrade.
• uninstall.
• health check.
• collect metrics.
• collect usage.
• render config.
• validate config.

Future runtime support must be added by plugin metadata and adapter implementation. Core Control Plane logic should not branch on concrete runtime names except through the runtime plugin registry.

8. Breaking Migration Policy

The new model is a breaking upgrade.

Rules:

• Do not keep Gateway as the generic name for every node.
• Do not keep ingress and egress as top-level gateway types.
• Do not add compatibility aliases such as /gateways meaning /nodes in new product documentation.
• Do not write application fallback logic for legacy fields.
• Do not keep legacy fields only to support old rows.
• Use SQL migrations for existing database rows and schema.
• Program code should read and write only the new model after migration.
• Ent schema should represent the target model, not historical transition states.
• Proto and OpenAPI may be broken during this development phase.
• Console routes and labels should move directly to the new product language.

Required migration direction:

9. Implementation Alignment Sequence

Functional development is paused until current MVP behavior is aligned with this model.

Required sequence:

1. Update documentation and terminology.
2. Generate SQL migration for schema changes.
3. Apply production and development database migration manually or through the agreed deployment path.
4. Update Ent schema to match the migrated structure.
5. Update proto and OpenAPI contracts directly to the new model.
6. Update Control Plane services to use Node, Capability Binding, Runtime Binding, Endpoint, and Subscription terms.
7. Update Edge Runtime protocol fields after Control Plane contracts are ready.
8. Update Console routes and labels according to the Console Information Architecture.
9. Run smoke tests on the existing Traffic MVP.
10. Resume feature development only after existing workflows are aligned.

Migration rules:

• SQL owns historical data transformation.
• Ent auto migration may create or adjust tables only when it matches the target structure.
• Program code must not contain historical backfill or legacy interpretation logic.
• Old columns should be dropped after their values are migrated.
• Old enum values such as top-level ingress or egress should be replaced by capability roles such as traffic.entry and traffic.exit.
• Old route names and UI labels should be replaced, not hidden behind compatibility wording.

10. Current MVP Alignment

The current MVP should be described as:

Traffic MVP
  Nodes:
    - tencent-hk
    - hermes-agent
    - aws-test

  Runtime:
    - sing-box

  Capability roles:
    - traffic.entry
    - traffic.exit

  User-facing resources:
    - subscriptions
    - traffic policies
    - usage and quota
    - domains and certificates

Do not describe the current MVP as a sing-box panel or as an ingress/egress gateway product.