Quickstart

This guide takes you from a fresh Linux 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 as a systemd service.
• A pre-existing workload published as https://<generated-name>.edgible.app.

The path uses the canonical Application v3 YAML model.

Prerequisites

• A Linux machine (Ubuntu 22.04+, Fedora, or a modern equivalent). The agent has been tested most heavily on Debian-family systems.
• Root / sudo access on that machine. The agent manages WireGuard, iptables, and a Caddy install — all need elevated privileges.
• Outbound HTTPS reachable. The agent talks to api.v2.dev.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. 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 ten 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 \
     --type systemd \
     --device-type serving \
     --device-name my-first \
     --non-interactive

   This registers a new device named my-first in your organization, generates its credentials, and installs a systemd unit. Installation takes 30–60 seconds.

3. Start the agent.

   sudo edgible agent start

   You can confirm with sudo systemctl status edgible-agent. The agent will connect to the control plane over WebSocket within a few seconds.

4. Verify the device is healthy.

   edgible device health --name my-first

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

5. 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.

6. 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: { mode: 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).

7. 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.

8. Watch the deployment finish.

   edgible stack status -f app.yml

   You’ll see the application move through pending → deploying → deploying_gateway → ready. The deploying_gateway step is where Edgible orders the TLS certificate and configures HAProxy on the gateway; this typically takes 30–90 seconds the first time.

9. Visit the URL.

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

   curl https://hello-world-a1b2c3.edgible.app/

   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.

10. (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-a1b2c3.edgible.app
       │
       ▼
Edgible Gateway  (HAProxy + WireGuard)
       │  encrypted tunnel
       ▼
Your machine      (Caddy on :443  →  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.
• Understand what’s happening under the hood. How it works and the Concepts section.