elide orb

Requires an Elide Pro license. See elide.pro for details.

When to use orb vs serve

Both commands share the same server engine. orb unlocks the premium configuration surface on top of it.

Prerequisites

• PKL config: A configuration file amending elide:serve/ElideServer.pkl is required (--config).
• Platform: Linux or macOS. Windows support is experimental.

---

Quick deploy

A reverse proxy fronting two backend servers, with a static SPA fallback:

amends "elide:serve/ElideServer.pkl"

servers {
  ["api.example.com"] {
    routes {
      new {
        match { path = "/v1/**" }
        handler = new ReverseProxy {
          upstreams { "backend-1:8080"; "backend-2:8080" }
          loadBalancing = "least_connections"
        }
      }
    }
    handler = new StaticFiles { root = "./dist"; spaFallback = true }
  }
}

 elide orb --config server.pkl

Elide reads the config, binds listeners, provisions TLS certificates if configured, and starts serving.

Add Tailscale in one flag

 elide orb --config server.pkl --tailscale

This binds to the node's Tailscale IP, provisions a Tailscale-issued TLS certificate (trusted by all tailnet devices), and registers MagicDNS.

Standalone Tailscale (no daemon)

Run as a self-contained Tailscale node — no tailscaled required. Elide embeds the TS2021 control plane, WireGuard data plane, and DERP relay client:

 elide orb --config server.pkl --tailscale-direct --tailscale-auth-key tskey-auth-...

Auto-HTTPS with ACME

Provision and auto-renew TLS certificates via Let's Encrypt:

 elide orb --config server.pkl --auto-https --domain example.com,www.example.com --acme-email admin@example.com

Or declare it entirely in PKL:

amends "elide:serve/ElideServer.pkl"

tls {
  acmeEmail = "admin@example.com"
}

servers {
  ["example.com"] {
    domains { "example.com"; "www.example.com" }
    handler = new StaticFiles { root = "./dist" }
  }
}

DERP relay co-hosting

Host a DERP relay alongside the HTTP server for Tailscale-compatible peer relay:

 elide orb --config server.pkl --tailscale --derp

---

Capability matrix

Capabilities

Every capability below is configured through the PKL file, CLI flags, or both — no code changes needed.

Reverse proxy and load balancing

Route requests to upstream pools with round-robin, least-connections, IP-hash, random, first-healthy, or cookie-based session affinity. Health checks, circuit breakers, WebSocket proxying, and header rewriting are all configurable per-route.

handler = new ReverseProxy {
  upstreams {
    new { address = "backend-1:8080"; weight = 2 }
    new { address = "backend-2:8080"; weight = 2 }
    new { address = "backend-3:8080"; backup = true }
  }
  loadBalancing = "least_connections"
  timeout = 30.s
  preserveHost = true
  websocket = true
}

See the configuration guide for full ReverseProxy patterns and the serve configuration reference for the complete PKL schema.

Tailscale and WireGuard networking

Three Tailscale modes: local daemon, Tailscale Funnel, and standalone direct mode. Raw WireGuard tunnels for non-Tailscale peers. Multiple named networks can coexist — a production tailnet alongside a staging one, or a WireGuard VPN alongside a Tailscale network.

See Tailscale integration for deployment patterns and configuration.

Multi-network orchestration

Define independent network attachments in a single config. Each network has its own data plane, routing rules, and identity:

networks {
  ["production"] {
    tailscale { direct = true; authKey = env("TS_PROD_KEY") }
    tunnel { bridgeInbound = true }
  }
  ["office-vpn"] {
    wireguard { configFile = "./wg-office.conf" }
    tunnel { bridgeOutbound = true }
  }
}

L4 relay and gRPC proxy

TCP-level relay for raw throughput. gRPC proxying with HTTP/2 multiplexing. Both operate alongside HTTP routing on the same listeners.

Auto-HTTPS and private PKI

ACME certificate provisioning via HTTP-01, TLS-ALPN-01, and DNS-01 challenges. Wildcard certificates via DNS-01 with Cloudflare or webhook providers. On-demand TLS for dynamic hostname provisioning. Private CA and mTLS for internal services via elide cert.

DERP relay

Co-host a DERP (Designated Encrypted Relay for Packets) relay alongside the HTTP server. The relay operates independently and shuts down gracefully on exit. Useful for self-hosted Tailscale infrastructure or air-gapped environments where public DERP relays are unreachable.

Admin API

A separate HTTP server (isolated from the main pipeline) with health/readiness probes, live configuration view, route table, middleware summary, cache statistics, and an HTMX dashboard. Configurable via --admin-port, --admin-socket, or PKL. When bound to a non-loopback address without an explicit --admin-token, a random bearer token is auto-generated and printed to stderr.

Zero-downtime upgrades

Self-re-exec with inherited file descriptors. On upgrade signal, Elide downloads the new binary via a secure update mechanism, drains in-flight connections (GOAWAY on HTTP/2, WebSocket close frames, 30-second request drain), hands off listener file descriptors via the sidecar, then re-execs with --claim-fds to take over without dropping a single connection.

Middleware pipeline

All middleware from elide serve is available: compression, rate limiting, CORS, basic auth, Tailscale identity auth, header manipulation, path rewriting, request ID injection, access logging, and body size limits.

---

CLI reference

elide orb [OPTIONS]

Related commands

See also

• Orb configuration guide — real-world config patterns for reverse proxy, TLS, multi-network, and admin API
• Tailscale integration — daemon mode, standalone mode, Funnel, DERP, and multi-network
• elide serve — HTTP server for static files, JS handlers, and CGI