Security

Trust Policies

The [trust] section in agents.toml controls which skill, subagent, and plugin 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

When defaultRepositorySource = "gitlab", shorthand trust sources are stored as GitLab domain rules, such as gitlab.com/my-company.

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 managed skills, subagents, and plugins and records where they came from. It is auto-generated. Project init adds it to .gitignore; global lockfiles live under ~/.agents/.

# 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"
resolved_commit = "0123456789abcdef0123456789abcdef01234567"

[subagents.code-reviewer]
source = "getsentry/agent-pack"
resolved_url = "https://github.com/getsentry/agent-pack.git"
resolved_path = "agents/code-reviewer.md"
resolved_commit = "fedcba9876543210fedcba9876543210fedcba98"

[plugins.review-tools]
source = "getsentry/agent-plugins"
resolved_url = "https://github.com/getsentry/agent-plugins.git"
resolved_path = "plugins/review-tools"
resolved_commit = "0123456789abcdef0123456789abcdef01234567"

Field	Description
`source`	Original source from agents.toml
`resolved_url`	Resolved git clone URL or HTTP base URL
`resolved_path`	Path within the source where the dependency was found
`resolved_ref`	Resolved ref name, omitted for default branch
`resolved_commit`	Installed commit SHA. Informational only

Explicit local path: dependencies and unscoped local wildcards have source only. Scoped local wildcards record resolved_path so offline sync can enforce the configured path scope. Subagent and plugin entries use the same fields under [subagents.<name>] and [plugins.<name>].

list and offline sync filter wildcard entries when resolved_path is available. Legacy entries without that metadata remain selected until a successful install refreshes the lockfile.

Caching

Cloned repositories are cached at ~/.local/dotagents/, and you can override that with DOTAGENTS_STATE_DIR.

Shallow clone per git source.
All git operations are non-interactive with GIT_TERMINAL_PROMPT=0.
Git sources refresh on every install.
Well-known HTTPS sources use a 24-hour TTL.