Nebula Gateway

The Nebula gateway is used to connect to a Nebula overlay network. It is not a system-level VPN, does not modify system network settings, and does not affect other apps' network traffic. It only provides a data channel for resources within OmniGate.

Nebula manages node identity through certificate signing: generate a CA and node certificates with nebula-cert on your server, then paste the node certificate, private key, and CA certificate — together with the entire config.yaml — into the app. It runs tun-less in userspace (with the Nebula stack and a gVisor TCP/IP stack embedded), exposing a local SOCKS5 proxy that Web, SSH, VNC, RDP, and WebDAV resources connect through.

Configuration

Field	Description
Name	Gateway display name
config.yaml	The complete Nebula configuration, pasted as-is; certificates are written as inline PEM under pki (see below)
Local Proxy Address	Default 127.0.0.1
Local Proxy Port	Default 9083
Auto-Connect on Launch	Automatically activate this gateway when the app opens, disabled by default

Inline Certificate Format

The values of pki.ca / pki.cert / pki.key are the PEM text itself, written as YAML block literals with |. Do not use file paths — those files do not exist in the iOS sandbox; only the inline form is supported.

pki:
  ca: |
    -----BEGIN NEBULA CERTIFICATE-----
    (full contents of ca.crt)
    -----END NEBULA CERTIFICATE-----
  cert: |
    -----BEGIN NEBULA CERTIFICATE-----
    (full contents of host.crt)
    -----END NEBULA CERTIFICATE-----
  key: |
    -----BEGIN NEBULA X25519 PRIVATE KEY-----
    (full contents of host.key)
    -----END NEBULA X25519 PRIVATE KEY-----

Notes:

• The certificates use Nebula's own format with the banner NEBULA CERTIFICATE — not X.509's -----BEGIN CERTIFICATE-----. X.509 certificates are unrelated to this gateway.
• pki.cert must contain only this node's certificate; do not append the CA certificate. The CA belongs in pki.ca only.
• Only plaintext private keys are supported: NEBULA X25519 PRIVATE KEY (or NEBULA P256 PRIVATE KEY). Encrypted keys generated by nebula-cert -encrypt-key cannot be used — decrypt them or re-sign first.
• With v2 certificates the banner is NEBULA CERTIFICATE V2; dual v1 + v2 certificates can be pasted as consecutive blocks under cert.
• Every line inside a | block must share the same indentation, deeper than the key. Do not use tabs.
• You can paste the tun section as usual; the app automatically runs in tun-less mode, no special settings required.

Minimal Configuration Example

The following is a ready-to-adapt client configuration template:

pki:
  ca: |
    -----BEGIN NEBULA CERTIFICATE-----
    ...
  cert: |
    -----BEGIN NEBULA CERTIFICATE-----
    ...
  key: |
    -----BEGIN NEBULA X25519 PRIVATE KEY-----
    ...

lighthouse:
  am_lighthouse: false
  interval: 60
  hosts:
    - "lighthouse-public-address:4242"

static_host_map:
  "lighthouse-nebula-ip": ["lighthouse-public-address:4242"]

listen:
  host: 0.0.0.0
  port: 0

tun:
  disabled: false
  dev: nebula0

firewall:
  outbound:
    - port: any
      proto: any
      host: any
  inbound:
    - port: any
      proto: any
      host: any

Basic Workflow

1. Generate the CA and node certificate on your server:

   nebula-cert ca -name "my-ca"
   nebula-cert sign -name "iphone" -ip "192.168.100.2/24" \
     -ca-file ca.crt -ca-key ca.key

2. Write config.yaml using the contents of ca.crt, iphone.crt, and iphone.key, inlining the certificates as described above.
3. Add a Nebula gateway in the app and paste the entire config.yaml.
4. Save and connect. Once the status shows connected, open resources using the peer's Nebula IP as the address.

Common Issues

Peer can be pinged, but web pages or SSH won't open

The Nebula firewall denies everything by default; allowing ICMP does not mean TCP is allowed. Check both ends:

• The firewall.outbound in the config.yaml you pasted must allow the target port (the template above already allows any).
• The peer's firewall.inbound must allow the corresponding TCP port, for example:

  firewall:
    inbound:
      - port: 8080
        proto: tcp
        host: any

• The peer's service must listen on its Nebula IP (bind to 0.0.0.0 or that IP); a service bound only to 127.0.0.1 is unreachable.

Cannot open addresses on the peer's LAN

This gateway can only reach Nebula IPs within the certificate's network. unsafe_routes (subnet forwarding to reach a peer's LAN) is a TUN-device feature and is not supported in the app's userspace mode. To reach LAN services behind a peer, have the peer run a port forward or reverse proxy on its Nebula IP.

Connection fails with a certificate error

Nebula certificates have a validity period (1 year by default); handshakes fail after expiry — re-sign the node certificate and update the pasted configuration. Private-key errors usually mean an encrypted key was pasted or the banner doesn't match; see the inline format notes above.

Current Implementation Notes

The complete Nebula stack is embedded in the app (pure Go implementation), without creating a system VPN. It only serves resources within OmniGate and will not route other apps' traffic through the Nebula network. The local SOCKS5 proxy port can be changed; avoid conflicting with other gateways' ports.

Auto-Connect

The Nebula gateway supports an "auto-connect on launch" toggle. When enabled:

• The app automatically activates this gateway on startup.
• The gateway list will display an auto label for this gateway.
• Enabling the toggle will immediately trigger a connection and save the configuration.

When disabled, the gateway list shows a lazy label, and the gateway will only connect when you open a resource under that gateway.

Enabling auto-connect saves the time spent waiting for the gateway to connect, but it increases app memory usage and battery consumption. It is recommended to enable this only for frequently used gateways.