Install the agent without sudo

The Edgible agent installs one of two ways, and the only thing that picks between them is whether you type sudo:

sudo edgible agent install     # a system service: starts at boot, runs with nobody logged in
edgible agent install          # under your own account: no sudo, nothing system-wide

There is no flag to learn and no setup step before either one. This page is about the second command — what you get, what you give up, and how to switch later.

Installing without sudo is the right choice on a shared or hardened machine, on one where you do not have standing administrator rights, or simply when you would rather not give a background service system-wide privileges.

What you get

Run edgible agent install as an ordinary user and the agent:

• Runs as you. A per-user service — a systemd --user unit on Linux, a LaunchAgent on macOS — started and stopped under your own account.
• Keeps its files in your own data directory. Config, logs, status and storage all land under your home directory, never in /etc, /var/lib or /Library.
• Uses its built-in secure tunnel. The agent carries its own WireGuard implementation, so it opens no network device and needs no privilege. Nothing in the machine’s network settings changes — no interfaces, no routes, no firewall rules.

Everything after the install works the same way, with no sudo anywhere:

edgible agent status
edgible agent logs --follow
edgible agent restart
edgible agent uninstall

On Linux the unit is an ordinary user unit, so systemctl --user status edgible-agent and journalctl --user -u edgible-agent work too. On macOS the job lives in your own launchd domain: launchctl print gui/$(id -u)/com.edgible.agent.

What the install tells you first

Before it writes anything, edgible agent install prints a short summary of what this choice means on this machine and asks whether to continue. On Linux it reads roughly like this:

Installing under your account (no sudo)

  The agent runs as alice and keeps its files in /home/alice/.local/share/edgible/agent.
  Its secure tunnel is built in, so nothing in this machine's network settings is changed.
  It stops when you log out, and does not start at boot, until you run once:
      sudo loginctl enable-linger alice
  Or install it as a system service instead: sudo edgible agent install
  Apps that need their own system services cannot run on this device without sudo.

? Install the agent under your account? (Y/n)

--yes skips the question. It never skips the summary — a scripted install still prints what it is about to do.

The one caveat: staying up after you log out

A per-user service is tied to your login session, and each platform handles that differently.

Linux

By default the agent stops when you log out (or when your SSH session ends) and does not come back at boot. One command, run once per account, changes that:

sudo loginctl enable-linger $(id -un)

That is the only place sudo appears in this flow, and it is optional — the install works without it, and warns you (EDG143) so the device does not quietly go offline the next time you disconnect. Run it and the agent starts at boot and survives logout.

macOS

macOS has no equivalent setting. A LaunchAgent exists only inside a login session, so an agent installed under your account starts when you log in and stops when you log out. The install reports this as a warning rather than a green tick, because a green tick would imply the device stays online.

If a Mac needs to stay online with nobody logged in, install it as a system service instead:

sudo edgible agent install

What you cannot do without sudo

• Gateway devices. They need administrator rights, and the CLI refuses up front rather than half-installing one (EDG140).
• Applications that need their own system services. A workload published as a system service writes system-wide unit files, which an unprivileged agent cannot do (EDG141). Deploy those applications as compose, managed-process or pre-existing workloads, or run this device’s agent with sudo.
• Windows. Installing the agent on Windows needs an Administrator prompt; there is no per-user install there.

Docker workloads deserve a note of their own: the agent process is unprivileged, but the Docker daemon it drives over the socket is not, and access to that socket is administrator-equivalent on the host no matter how the agent was installed. The install says so (EDG123).

One agent per machine

A machine can hold one agent. If the agent is already installed the other way — a system service from an earlier sudo edgible agent install, or a per-user one from an earlier install without sudo — the new install stops before it writes anything and names the uninstall that clears the way (EDG145):

✗ EDG145 The agent is already installed on this machine as a system service
         (/etc/systemd/system/edgible-agent.service).
  Fix: Remove that install first: sudo edgible agent uninstall

The uninstall has to be run the way the original install was — with sudo if it was installed with sudo, without if it was not.

Switching from one to the other

There is no in-place conversion. Uninstall, then install the other way:

# from a per-user install to a system service
edgible agent uninstall
sudo edgible agent install

# from a system service to a per-user install
sudo edgible agent uninstall
edgible agent install

The device itself is unaffected by the uninstall — re-installing binds this machine to the same device again.

If the install cannot write to your data directory

The most common failure on a per-user install is a folder an earlier sudo edgible command created as root, which your own account can no longer write to. The install reports EDG101 and hands you the fix verbatim:

sudo chown -R "$(id -un)" ~/.local/share/edgible

Then re-run edgible agent install.

Where to go next

• Quickstart — a device and a public HTTPS URL in about ten minutes.
• Error codes — every EDG### the install can print.
• edgible agent reference — every flag on every agent command.