Quickstart

This guide takes you from a fresh machine to a public HTTPS URL that serves a real response, in roughly ten minutes. By the end you will have:

• An Edgible account, logged in on your machine.
• The Edgible agent installed and running on that machine.
• A pre-existing workload published as https://hello-world.<your-org>.edgible.com.

The path uses the canonical Application v3 YAML model.

Prerequisites

• A Linux or macOS machine on x86_64 or arm64. This guide uses a Debian-family Linux host (Ubuntu 22.04+ or Debian) for its commands; the installer also drives dnf, yum, apk and Homebrew when it needs to fetch a missing tool, so a Fedora, Alpine or macOS host works with its own package manager’s names.

• Either sudo access or not — both work, and the choice is yours. sudo edgible agent install gives you a system service that starts at boot and runs with nobody logged in; edgible agent install without sudo installs it under your own account and changes nothing system-wide. This guide uses the sudo form. See Install the agent without sudo for the other one.

• Outbound HTTPS reachable. The agent talks to api.v2.prod.edgible.com over TCP/443. No inbound connectivity is required.

• An Edgible account. If you don’t have one, sign up first — you’ll receive an email and password.

• The edgible CLI installed and on your PATH:

  curl -fsSL https://get.edgible.com/install.sh | bash

  The CLI needs Node.js 20+ — the installer offers to install it if it’s missing. Run edgible --version to confirm.

Tip

A single device is enough. The Edgible-managed gateway handles the public side automatically — you don’t need to provision a second machine.

The nine steps

1. Log in.

   edgible auth login \
     --user-email you@example.com \
     --user-password 'your-password'

   The CLI writes auth tokens and your active organization ID to a config file under your user home directory.

2. Install the agent.

   sudo edgible agent install \
     --device-type serving \
     --device-name my-first \
     --yes

   Or, if you would rather not give a background service system-wide privileges, drop the sudo:

   edgible agent install \
     --device-type serving \
     --device-name my-first \
     --yes

   That one difference decides everything else, and the command prints a short summary of what it means on your machine before it writes anything (--yes skips the question, never the summary). Either way it registers a new device named my-first in your organization, generates its credentials, installs the service and starts it. Installation takes 30–60 seconds.

3. Verify the device is healthy.

   edgible device health --device my-first

   Expect a Health check OK response within ten or fifteen seconds. If this hangs, see Troubleshooting.

4. Start something to serve.

   For this walkthrough we’ll use Python’s built-in HTTP server as the placeholder workload. Run it on the device, in the background, on port 8080:

   python3 -m http.server 8080 &

   Anything listening on 127.0.0.1:8080 will work — substitute your own service if you have one ready.

5. Author the application YAML.

   Save the following as app.yml somewhere on the same machine. Replace <your-org-id> with your organization ID — edgible config list will show it.

   app.yml

   apiVersion: v3
   kind: Application
   metadata:
     name: hello-world
     organization: <your-org-id>
   spec:
     placement:
       strategy: serving-device
       deviceSelector:
         deviceName: my-first
     workloads:
       - name: web
         type: pre-existing
         hostPort: 8080
         ports:
           - { name: http, containerPort: 8080, protocol: tcp }
     access:
       - name: public
         type: https
         target: { workload: web, port: http }
         hostname: { generated: true }
         tls: { managedBy: edgible }
         policies:
           auth: { modes: [none] }

   What’s happening:

   • placement.deviceSelector.deviceName pins this application to the device you just installed.
   • The pre-existing workload tells Edgible there is already a process listening on hostPort: 8080.
   • One access entry exposes that port over HTTPS, on a hostname Edgible generates, with a managed TLS certificate, and no auth check (anyone can reach it).

6. Deploy.

   edgible stack deploy -f app.yml

   The CLI parses the file, validates it locally, and posts the application to the control plane. Within a second or two the agent on my-first will receive the update and start reconciling.

7. Watch the deployment finish.

   edgible stack status -f app.yml

   You’ll see the application move through pending → deploying → ready. While it’s deploying, Edgible orders the TLS certificate and configures the public route; the first deploy of an application typically takes 30–90 seconds.

8. Visit the URL.

   Once status is ready, the same stack status output (or edgible application get <app-name>) will show the generated hostname, something like hello-world.myorg.edgible.com.

   curl https://hello-world.myorg.edgible.com/

   You should see the directory listing Python’s HTTP server produces. That response is travelling over the public internet, into the gateway, through a WireGuard tunnel to your machine, through Caddy, into your python3 -m http.server, and back.

9. (Optional) Tear it down.

   edgible stack teardown -f app.yml

   The application is removed from the agent, Caddy stops serving the route, and the gateway forgets the hostname. The device itself stays installed and registered.

What you just built

https://hello-world.myorg.edgible.com
       │
       ▼
Edgible Gateway  (HAProxy + WireGuard)
       │  encrypted tunnel
       ▼
Your machine      (Caddy on :10222  →  python http.server on :8080)

The hostname is bound to your specific device for as long as the application exists. If you stop the Python server, the URL keeps responding 502 (because the workload is dead, not the route). If you delete the application, the hostname is released.

Where to go next

• Replace the placeholder with a real workload. Deploy a Docker Compose app walks through a multi-container example.
• Add a custom domain. Use a custom domain covers the DNS hand-off and a per-hostname certificate.
• Lock it down. Protect with API keys shows how to require a bearer token on every request.
• See who is calling it. Watching your traffic covers edgible application traffic and edgible application requests — status codes, latency, paths, clients and errors.
• Understand what the platform is doing. How it works and the Concepts section.