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.

You can also manage trusted sources from the CLI instead of editing TOML directly:

dotagents trust add getsentry                    # trust a GitHub org
dotagents trust add external-org/specific-repo   # trust a specific repo
dotagents trust add git.corp.example.com         # trust a git domain
dotagents trust list                             # show trusted sources

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

Lockfile

agents.lock tracks which skills are managed and where they came from. It is auto-generated and should be gitignored.

# 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"

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)

Local path: skills have source only.

Caching

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

Shallow clone per repo, refreshed after a 24-hour TTL
All git operations are non-interactive (GIT_TERMINAL_PROMPT=0)
Use dotagents install --force to bypass cache