Security - dotagents

Trust Policies

The [trust] section in agents.toml controls which skill sources are allowed. Trust is validated before any network operations in add and install. If a source does not match the policy, the command fails immediately.

No Trust Section (default)

When [trust] is absent, all sources are allowed. This is the default for backward compatibility.

# No [trust] section — all sources allowed
version = 1
agents = ["claude"]

[[skills]]
name = "any-skill"
source = "anyone/any-repo"

Allowlist Mode

Add a [trust] section to restrict sources to an allowlist. A source passes if it matches any rule.

[trust]
github_orgs = ["getsentry", "my-company"]
github_repos = ["external-org/one-approved-repo"]
git_domains = ["git.corp.example.com"]

Field	Matches	Example
`github_orgs`	GitHub sources where the owner matches	`"getsentry"` matches `getsentry/skills`, `getsentry/warden`
`github_repos`	Exact `owner/repo` match	`"external-org/one-approved-repo"`
`git_domains`	Domain extracted from `git:` URLs	`"git.corp.example.com"` matches `git:https://git.corp.example.com/team/repo`

Local path: sources are always allowed regardless of trust configuration.

Explicit Allow All

Use allow_all = true to make the intent explicit in shared repositories. This is functionally the same as omitting the section, but communicates that the choice was deliberate.

[trust]
allow_all = true

Integrity Verification

Every installed skill gets a SHA-256 integrity hash recorded in agents.lock. This hash is computed deterministically from the skill directory contents.

How It Works

Walk all files in the skill directory, sorted alphabetically
SHA-256 hash each file's contents
Concatenate <relative-path>\0<hex-hash>\n for each file
SHA-256 hash the concatenation
Base64-encode and prefix with sha256-

[skills.find-bugs]
source = "getsentry/skills"
resolved_url = "https://github.com/getsentry/skills.git"
commit = "c8881564e75eff4faaecc82d1c3f13356851b6e7"
integrity = "sha256-FWmCLdOj+x+XffiEg7Bx19drylVypeKz8me9OA757js="

Verification

dotagents list shows ~ for skills whose contents have been modified since install
dotagents sync verifies all integrity hashes and reports mismatches
dotagents install --frozen fails if hashes don't match after install

Frozen Installs (CI)

Use --frozen in CI to guarantee reproducible installs.

dotagents install --frozen

This mode:

Fails if agents.lock does not exist
Fails if any skill in agents.toml is missing from the lockfile
Fails if integrity hashes don't match after install
Does not modify the lockfile

Lockfile

agents.lock pins exact git commits and integrity hashes for every installed skill. It is auto-generated and should be committed to version control.

# Auto-generated by dotagents. Do not edit.
version = 1

[skills.find-bugs]
source = "getsentry/skills"
resolved_url = "https://github.com/getsentry/skills.git"
resolved_path = "plugins/sentry-skills/skills/find-bugs"
commit = "c8881564e75eff4faaecc82d1c3f13356851b6e7"
integrity = "sha256-FWmCLdOj+x+XffiEg7Bx19drylVypeKz8me9OA757js="

Field	Description
`source`	Original source from agents.toml
`resolved_url`	Resolved git clone URL
`resolved_path`	Subdirectory within repo where skill was found
`resolved_ref`	Resolved ref name (omitted for default branch)
`commit`	Full 40-char SHA
`integrity`	SHA-256 content hash

Local path: skills have source and integrity only.

Caching

Cloned repositories are cached at ~/.local/dotagents/ (override with DOTAGENTS_STATE_DIR).

Unpinned repos (owner/repo/): shallow clone, refreshed after a 24-hour TTL
Pinned refs (owner/repo@sha/): immutable, never re-fetched
All git operations are non-interactive (GIT_TERMINAL_PROMPT=0)
Use dotagents install --force to bypass cache