Skip to content

Sources and distribution

Distribution is outside the directory format. An overlay MAY be copied, archived, served over HTTP, listed in a catalog, kept inside a larger repository, or stored in version control.

Source form

Optional Extension. A consumer's configuration names where an overlay comes from with a source string:

source   = [ "git+" ] location [ "@" ref ] [ "#" path ]
  • location is a local path, an http or https URL, or a Git repository: one ending in .git, starting git@, ssh:// or git://, or prefixed git+.
  • ref exists only for a Git location: a branch, tag or commit, with no /, : or \. It is the part after the last @, when that @ is not part of git@host, a URL's user information, or a scheme. Absent, the remote's default branch. A URL's authority runs from after :// to the first / or ?, and an @ in it is always user information: git+https://evil.example@github.com names the host github.com with a user, and no ref.
  • path is the part after the first #: the overlay's root inside the location, with leading and trailing / removed; what remains is a relative path, or the source is refused. Absent, the location's root is the overlay.
  • A Git location is a local path, an scp-like user@host:path, or a URL whose scheme is https, http, ssh, git or file. A location holding :: (Git's remote-helper syntax, which runs a program) is refused, and so is a location, ref or host starting with -, since it would reach git or ssh as an option, and so is a user, port or scp-like path that starts with - once percent-decoded (ssh://%2doProxyCommand=x@host/a.git). A consumer passes the location after --, and limits Git's transports (protocol.allow) to the ones it accepts.
  • A source holds no control character (U+0000–U+001F, U+007F–U+009F), no U+2028 or U+2029 and no character that reorders displayed text (U+200E, U+200F, U+202A–U+202E, U+2066–U+2069), and an authority holds no \, which URL parsers read differently: what a person is shown must be what is fetched.
Source Kind Location Ref Path
./overlays/rust directory ./overlays/rust
https://github.com/example/agents.git@v2#overlays/rust git https://github.com/example/agents.git v2 overlays/rust
git@github.com:example/agents.git git git@github.com:example/agents.git
git+https://example.org/agents@main#rust git https://example.org/agents main rust
/srv/overlays@v2 directory /srv/overlays@v2
https://example.org/overlays/rust URL https://example.org/overlays/rust

A location is a Git location as above, else a URL when it contains ://, else a directory. Surrounding whitespace is removed first; an empty source is an error.

A pinned source pairs a source with a pin. For a reproducible install the ref is a full commit id (40 or 64 hexadecimal digits) and the pin is the tree digest; a branch or a tag can move.

A consumer that logs or stores a source removes any user information and query string from it first (https://user:secret@host/x.git?token=t is shown as https://host/x.git). Who writes a source limits what it can be: a catalog from elsewhere names nothing on the consumer's machine, and neither does a manifest, which holds no credential either.

Status: dotagents parses exactly this form (<location>[@<ref>][#<path>]) for repositories and overlays. It also reads registries (a JSON, TOML or YAML mapping from name or alias to source, relative entries resolved beside the registry: the minimal form of a catalog) and, with optional dependencies, URI schemes such as zip:, sftp: and s3:. It consults --repo, then AGENTS_OVERLAYS_REPO_<KEY>, then AGENTS_OVERLAYS_REPO, then the project's and the user's dotagents.{json,toml,yaml,yml}; the first that offers a name wins. That order is dotagents policy.

Provenance

A manager records, for each installed overlay, the source with its user information removed, the resolved commit when there is one, the tree digest, and when it was fetched. It shows source and ref before it activates an overlay for the first time, and the difference before it updates one.

AOS does not require GitHub, Git, or any registry protocol.