> ## Documentation Index
> Fetch the complete documentation index at: https://docs.altnautica.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Install from a URL

> Hand a paired GCS an HTTPS link to a signed plugin and let the agent download, verify, and install it.

URL install is the second distribution mechanism. Local file install
remains the baseline. URL install lets a paired Mission Control hand the
agent an HTTPS link to a published `.adosplug`; the agent downloads it,
verifies the signature, and runs the same install flow as a local file.

## How it works

URL install is a GCS-driven flow, not a standalone agent command. The
GCS posts the URL to the agent's `POST /api/plugins/install_from_url`
endpoint. The agent downloads the archive directly (no intermediate
storage hop), then hands the bytes to the same installer that local file
install uses: archive parse, signature verify, manifest validation,
board-compatibility check, and permission gating all run unchanged. Only
the transport differs.

There is no `ados plugin install <url>` command. The agent CLI installs
from a local path; the URL path is reached through the GCS.

## When to use it

Local file install is right when you have the `.adosplug` on disk and
want a deterministic, sneakernet-friendly path. URL install is right
when you want the operator to paste a published release link into the
GCS instead of downloading the file first.

## GCS flow

In **Mission Control -> Settings -> Plugins -> Install plugin**, choose
**Install from URL**, paste the link, and submit. The GCS forwards it to
the agent over the host bridge. Once the agent has downloaded and parsed
the archive, the same permission dialog as local file install appears:
name, version, signer, risk band, and requested permissions for approval.

## Rules the agent enforces

| Rule              | Detail                                                                                                                                                                                                                                      |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| HTTPS only        | The URL scheme must be `https`. Plain `http://` is rejected.                                                                                                                                                                                |
| Host allowlist    | The default set is GitHub release assets (`github.com`, `objects.githubusercontent.com`), S3 (`amazonaws.com`), and `localhost` for dev rigs. The match is on the labelled host boundary, so `evil-github.com` does not match `github.com`. |
| Download size     | The streamed body is capped at 100 MB and aborts mid-stream once it exceeds the cap. The archive itself must also fit the 50 MB plugin-archive limit at parse time.                                                                         |
| Optional hash pin | When the caller supplies an expected SHA-256, the agent compares it against the streamed bytes and aborts on mismatch.                                                                                                                      |
| Timeouts          | 60 seconds to open the connection, 5 minutes total.                                                                                                                                                                                         |

A URL whose host is not on the allowlist is rejected before any bytes
are downloaded.

## Self-hosted release hosts

The host allowlist ships with the GitHub and S3 defaults so a plugin
published to a GitHub release works out of the box. Hosting archives on
your own server is a reserved extension point: the allowlist is a
configurable constant, and pointing the agent at an internal release
host means extending that allowlist in the agent configuration. The v1
defaults do not include arbitrary internal hosts.

## Integrity is identical to local install

Once the bytes are on disk, URL install and local file install are the
same flow. The signature is checked against the agent's trusted key
list, the manifest is validated, board compatibility is enforced, and
permissions are gated. A signer the agent does not trust fails the
install no matter how the archive arrived. The transport adds the host
allowlist, the size cap, and the optional hash pin on top.

## What this is not

URL install is not the registry. There is no search, no version
listing, no install count, and no review queue. It is local file install
with the file fetched over HTTPS first, restricted to allowlisted hosts.

## See also

* [Local file install](/developers/distribution-local-install)
* [Hosted registry (planned)](/developers/distribution-registry)
* [Signing keys](/developers/signing-keys)