policy

package
v0.7.14-dev.10 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 3, 2026 License: MIT Imports: 22 Imported by: 0

Documentation

Overview

Package policy loads the operator policy — the machine-side half of every run plan. The manifest says what an agent wants; the policy says what this operator's machine will provide: image pins, the model endpoint and its egress allowlist, whether wildcard egress is ever runnable, and where secret values come from. The policy participates in the plan hash, so changing it invalidates installed plans instead of silently changing what they mean.

Index

Constants

View Source
const (
	DefaultGatewayImage = "ghcr.io/blaktron/agentry-mcp-gateway:v0.44.3@sha256:bae58d801fd4b73f6ad91e609b8ce5ec8868713825f33a2bb20a98f956d0bd46"
	// DefaultHarnessImage is Docker Agent built from its pinned upstream
	// commit by agentry-dockerimages (build/docker-agent/), amd64 and arm64,
	// and signed keyless by that repository's docker-agent workflow on main;
	// CI holds this pin to that signature (scripts/verify-docker-agent-image.sh).
	// It is pinned by digest: the tag is a label, the digest the bytes, and
	// the receipt names it.
	DefaultHarnessImage = "" /* 134-byte string literal not displayed */
	DefaultGoBuilder    = "ghcr.io/blaktron/agentry-golang-alpine:1.27-alpine@sha256:d200d2dd76b03a99b52651fd1325aff7dcd35422c35c01bac56571b0507f3deb"
	// Runtime images that install and run declared npm/PyPI MCP servers.
	// Node is 26, the current release: a server whose engines.node needs a
	// newer major than its runtime's fails every tool call (the OSV advisory
	// server declares >=24.0.0 in every version, and 0.1.14 and later do
	// fail on 22, Promise.try).
	// Both are pinned by digest: an install pulls a runtime only when the
	// engine lacks the reference, so a tag would leave a machine on the
	// image it first pulled, CA bundle and all.
	DefaultNodeRuntime = "ghcr.io/blaktron/agentry-node-alpine:26-alpine@sha256:c6ad9e9c1d80f6eb607c26b4b0a132ff7a2344fad1c78ea3baa2a7d4c8de6d94"
	// Python is Debian's (glibc), not Alpine's (musl): many PyPI packages
	// publish only manylinux wheels (onnxruntime, scikit-learn), and a
	// server that depends on one cannot resolve on musl at all.
	DefaultPythonRuntime = "ghcr.io/blaktron/agentry-python-slim:3.15-slim-trixie@sha256:94d3426f1def7db4a106a232ac121bfd975393e5dfd40a619b955fae45fe7913"
	// The Node and Python the two default runtimes run, as `node --version`
	// and `python3 --version` print them in the digests images.tsv pins:
	// the versions a declared server's own engines.node
	// or requires_python must admit for its runs to work, which the Drafter
	// is told and its post-step holds. A test holds each to its image's tag.
	DefaultNodeVersion   = "26.13.0"
	DefaultPythonVersion = "3.15.2"
	// DefaultPythonFallbackRuntime is the Python runtime a PyPI server runs on
	// when its requires_python excludes DefaultPythonRuntime's Python but
	// admits this one: the previous Python line, on the same Debian base,
	// pinned by digest. A policy that sets pythonRuntime to its own image
	// never reaches it (mcpinstall.ChoosePython).
	DefaultPythonFallbackRuntime = "ghcr.io/blaktron/agentry-python-slim:3.14-slim-trixie@sha256:cd89c30eda26ee911a4611b18680086e0ea42e6f5f8cbe653d07fa7958c9cec8"
	// DefaultPythonFallbackVersion is the Python that image runs, held to its
	// tag by a test as DefaultPythonVersion is.
	DefaultPythonFallbackVersion = "3.14.10"
	// DefaultUnsafeImage is the Unsafe Mode base: Kali with a
	// command index and an extras list, pinned by digest, amd64 and arm64.
	// It moves with a CLI release, re-pinned monthly. The index also holds
	// the programs the base itself carries through alternatives links or
	// that Contents left ambiguous.
	DefaultUnsafeImage = "ghcr.io/blaktron/agentry-unsafe-kali:2026.10.30.6@sha256:3e56f7a740b69abfa812be77a0c055bf4693a2092bb68b0bf2aade2585123567"
	// DefaultFilesImage is the files image, the decoders and the malware check
	// the decode step runs: pandoc, pdftotext, tesseract, Tika, libarchive and
	// clamscan on Alpine, amd64 and arm64, pinned by digest and pulled, never
	// built at run time. The digest is signed keyless by agentry-dockerimages'
	// files workflow, and CI holds this pin to that signature
	// (scripts/verify-files-image.sh); a run pulls by digest only.
	DefaultFilesImage = "ghcr.io/blaktron/agentry-files:2026.10.30.6@sha256:effd241f134ca038a6a50d27dc637b56c85b41a683a17f1e662bf6151fb129de"
	// DefaultHostlinkImage is the host link's base, the OpenSSH client a run
	// reaches a target host with: Alpine's ssh, sftp and ssh-keyscan, amd64 and
	// arm64, uid 10001, pinned by digest and pulled; the CLI copies its runner
	// binary in. Signed keyless by agentry-dockerimages' hostlink workflow, and
	// CI holds this pin to that signature (scripts/verify-hostlink-image.sh).
	DefaultHostlinkImage = "ghcr.io/blaktron/agentry-hostlink:2026.10.30.4@sha256:2095280de958ddf973b21cd76462d0ffb1418ab2cf28dd2ad1489c71620a9b2d"
	// DefaultBrowserImage is the browser server's image, for a release that
	// declares capabilities.browser: Microsoft's @playwright/mcp 0.0.83
	// driving Debian's open-source Chromium (its executable named by the
	// image's PLAYWRIGHT_MCP_EXECUTABLE_PATH) with a Chromium policy that
	// turns ECH off, on the debian:trixie-slim mirror, amd64 and arm64,
	// pinned by digest and pulled. Signed keyless by agentry-dockerimages'
	// browser workflow, and CI holds this pin to that signature
	// (scripts/verify-browser-image.sh).
	DefaultBrowserImage = "ghcr.io/blaktron/agentry-browser:2026.10.30.5@sha256:8344cb900a301d292fbbb5e4399bc9db8e9604896f863c4ad4ea064f86cd894d"
	// DefaultCoderImage is the Coding agent's toolchain, the base its exec
	// container is built on: Debian 13's build tools (GCC, Make, CMake,
	// pkg-config), Git, curl, Python 3 with pip and venv, Go and Node with
	// npm, the git hosts' CLIs (gh, glab, tea) and the scanners osv-scanner
	// and gitleaks, amd64 and arm64, uid 10001, no setuid file, no sudo and
	// no SSH client, pinned by digest and pulled; the CLI copies its runner
	// binary in. Signed keyless by agentry-dockerimages' coder workflow, and
	// CI holds this pin to that signature (scripts/verify-coder-image.sh).
	DefaultCoderImage = "ghcr.io/blaktron/agentry-coder:2026.10.30.6@sha256:9ad69c8edfa05420a254da5825537bce88b00a637d6f2bc9212a0805b60aee63"
	// DefaultGogImage is gog, the Google Workspace CLI whose `gog mcp` mode
	// serves Gmail, Calendar, Drive, Docs and Sheets as MCP tools, read-only
	// unless started with --allow-write: built from gog's pinned source,
	// amd64 and arm64, uid 10001, pinned by digest. Signed keyless by
	// agentry-dockerimages' gog workflow, and CI holds this pin to that
	// signature (scripts/verify-gog-image.sh).
	DefaultGogImage = "ghcr.io/blaktron/agentry-gog:0.47.1-2026.10.30.3@sha256:339dcf0d6b2d8b60c96f09cfa4b71ffab0b1fe6e6acfa8d996bc19af468a1d3a"
	// DefaultMS365Image is Softeria's ms-365-mcp-server, the Microsoft 365
	// and Outlook.com MCP server: mail, calendar, contacts and OneDrive over
	// stdio, the tools each switch allows named by --enabled-tools, its token
	// cache sealed by the image's own keeper under a key the runner gives
	// it, its account tools left out of stdio mode: built from its pinned
	// source with Microsoft Graph's OpenAPI documents pinned, amd64 and
	// arm64, uid 10001, pinned by digest. Signed keyless by
	// agentry-dockerimages' ms365 workflow, and CI holds this pin to that
	// signature (scripts/verify-ms365-image.sh).
	DefaultMS365Image = "ghcr.io/blaktron/agentry-ms365:0.177.0-2026.10.30.3@sha256:0eb25196cd762512b6220bf66f5de587045a1fec0849e5c7d4946e798425ed0e"
	// DefaultClamAVSignatures is the ClamAV signature bundle the decode step
	// checks every input against: a tag agentry-dockerimages' clamav-db
	// workflow moves daily, only ever to a digest it has signed. It is not
	// pinned, by design; the CLI verifies that signature at each refresh
	// (pkg/runner/clamdb).
	DefaultClamAVSignatures = "ghcr.io/blaktron/agentry-clamav-db:latest"
	// Default trusted repositories for capabilities.mcpServers.
	DefaultNPMRegistry  = "https://registry.npmjs.org"
	DefaultPyPIRegistry = "https://pypi.org"
)

Default image pins. These are Agentry's own mirrors and builds, published from blaktron/agentry-dockerimages: each mirror's destination digest was verified equal to the upstream digest it mirrors, so the bytes are what the upstream tag named when it was pinned. Every default is pinned by digest (name:tag@sha256:…): the digest fixes the bytes and the tag is a label for a reader, so a tag pushed again, or a mistaken re-mirror, cannot change what a run pulls. Only the signature database (DefaultClamAVSignatures) is a tag, by design.

DefaultGoBuilder is one of the two bases of the runner image. Its Go must be at least go.mod's go line, to the patch: the runner context's go.mod names that line (runnerimage) and an older builder refuses it, so a go bump re-mirrors and re-pins this in the same change. The image is built, not pulled, so the ref only ever reaches a Dockerfile FROM; the runtime base is pinned the same way in runnerimage/Dockerfile.

View Source
const (
	DefaultMemory = "2g"
	DefaultCPUs   = 1
	DefaultPids   = 512
)

The defaults: enough for the docker-agent harness and a declared server's install; not a sizing for several runs on one host, which is the hosted plan's to choose. One CPU because docker refuses more than the host has, and because it is what the gateway already gave the containers it launches.

View Source
const (
	MinContextWindow = 1024
	MaxContextWindow = 1 << 30
)

MinContextWindow and MaxContextWindow bound model.contextWindow: below the floor a harness's own summary request and output budget would not fit, and above the ceiling no model's window lies (a number that large is an endpoint's mistake, and would hold compaction back for good).

View Source
const (
	DefaultJudgeKeyEnv     = "TYPESAFE_API_KEY"
	DefaultWebSearchKeyEnv = "YDC_API_KEY"
	BraveSearchKeyEnv      = "BRAVE_API_KEY"
	TavilySearchKeyEnv     = "TAVILY_API_KEY"
	ExaSearchKeyEnv        = "EXA_API_KEY"
	PerplexitySearchKeyEnv = "PERPLEXITY_API_KEY"
	JudgeKeyProvider       = "typesafe"
	// DefaultHybridKeyEnv is the Hybrid Analysis key's variable, the one a
	// sandbox host hands the CLI the platform's key in;
	// HybridKeyProvider its keychain entry's.
	DefaultHybridKeyEnv = "HYBRID_API_KEY"
	HybridKeyProvider   = "hybrid-analysis"
)

The default variables the person's own keys are read from, and the keychain provider name of the Jev key. DefaultWebSearchKeyEnv is You.com's, the first search provider.

View Source
const (
	DefaultModelProvider  = "anthropic"
	DefaultModelName      = "claude-sonnet-5-5"
	DefaultModelAPIKeyEnv = "ANTHROPIC_API_KEY"
	DefaultModelHostPort  = "api.anthropic.com:443"
)

Default returns the built-in policy. The model a fresh policy names: the provider the setup command offers first and that provider's newest release line, with the variable its key is read from and the one host the agent container may reach for it. The setup command's provider table reads these, so the two never disagree.

View Source
const (
	KeyKindAPI          = "api"
	KeyKindSubscription = "subscription"
	ProviderAnthropic   = "anthropic"
)

The apiKeyKind values: what an Anthropic credential is, read from its shape. ProviderAnthropic is the one provider whose keys come in two kinds.

View Source
const (
	// KeyKindChatGPTPlan spends a ChatGPT plan through OpenAI's "Sign in
	// with ChatGPT" plan usage: the run is handed a short-lived access
	// token in a read-only file, rewritten before it expires.
	KeyKindChatGPTPlan = "chatgpt-plan"
	// KeyKindClaudeSignIn spends a Claude subscription through Claude
	// Code's own sign-in, kept in a config directory Agentry owns and
	// never reads.
	KeyKindClaudeSignIn = "claude-signin"
	// KeyKindCopilotSignIn spends a Copilot plan through a GitHub sign-in.
	KeyKindCopilotSignIn = "copilot-signin"

	ProviderOpenAI  = "openai"
	ProviderCopilot = "copilot"

	// ProviderVultr is Vultr Serverless Inference, an OpenAI-compatible
	// endpoint paid by a key from the person's Vultr account.
	ProviderVultr = "vultr"

	// ProviderAgentry pays for the model with the credits of the account
	// signed in to a SecureAgentry registry: an OpenAI-compatible endpoint
	// under the registry's own address (AgentryInferencePath), reached with
	// a session token the host opens for each run, never with a key.
	ProviderAgentry = "agentry"

	// The providers whose account a person may connect:
	// each is paid by an ordinary API key (or, Hugging Face, an inference
	// token), pasted or minted by a connect.
	ProviderOpenRouter  = "openrouter"
	ProviderPoe         = "poe"
	ProviderHuggingFace = "huggingface"
)

The model sign-in kinds, and the providers they belong to.

View Source
const (
	TokenRouteAuthCommand = "auth-command"
	TokenRouteRestart     = "restart"
)

The token routes of HarnessPolicy.SignInTokenRoute.

View Source
const (
	CopilotPlanIndividual = "individual"
	CopilotPlanBusiness   = "business"
	CopilotPlanEnterprise = "enterprise"
)

The Copilot plans, by the Copilot API host each is served from, the other host a Copilot run reaches (GitHub's Copilot allowlist reference: *.individual, *.business and *.enterprise.githubcopilot.com). Copilot's telemetry and experiment hosts are hosts of their own, so the proxy denies them. Which host each plan uses is read from GitHub's docs, not measured.

View Source
const (
	PinDigest   = "digest"
	PinArtifact = "artifact"
	// PinTag is a harness image named by tag alone: only docker-agent's
	// may be, for a policy file written before the default was pinned. The
	// receipt says so.
	PinTag = "tag"
)

The ways a harness image is pinned, as plans and receipts name them.

View Source
const AgentryInferencePath = "/api/v1/x/inference/v1"

AgentryInferencePath is where a SecureAgentry registry serves its OpenAI-compatible model endpoint for credit-paid runs.

View Source
const CopilotGitHubAPI = "api.github.com:443"

CopilotGitHubAPI is GitHub's API, where Copilot CLI reads the account's entitlement and its organization's managed settings: one of the two hosts a Copilot run reaches.

View Source
const DockerAgentAdapter = "docker-agent"

DockerAgentAdapter is the default adapter's name, whose image is images.harnessImages.docker-agent (the adapter package names it too; it imports this one).

View Source
const HomeEnv = "AGENTRY_RUNNER_HOME"

HomeEnv relocates the runner home — the policy, the install cache, the profiles, the image context — as one tree, for tests and odd deployments.

View Source
const MaxCostSignInSentence = "" /* 223-byte string literal not displayed */

MaxCostSignInSentence is why a cost budget is refused for a run paid by a model sign-in: the plan pays, so the run reports tokens.

View Source
const NewestFile = "harness-newest.json"

NewestFile is the record, beside the policy file, of the newest vendor release of each harness this machine built an image of. A harness image the policy does not pin itself is built from its vendor's newest release when that release passes every check, and from the release this build of agentry pins and tested when it does not; the record says which, so a run takes the image setup made. It is the runner's own state, never the operator's: the policy file and its sha are unchanged by it.

View Source
const PersistentReleasesRefused = "the runner policy sets allowPersistentReleases: false, so only the persistent agents built into Agentry run on this computer"

PersistentReleasesRefused is the refusal of a persistent release under a policy that sets allowPersistentReleases false.

View Source
const ResolvConfTarget = "/etc/resolv.conf"

ResolvConfTarget is where a container reads its name servers.

View Source
const SubscriptionTokenSentence = "" /* 160-byte string literal not displayed */

SubscriptionTokenSentence is the one sentence every surface says about an Anthropic subscription token: what it drives and what it does not. Anthropic admits one from Claude Code alone (its terms since February 2026, and the API), so a run through any other harness would fail at the first model call.

View Source
const Version = "1"

Version is the current policy schema major.

Variables

View Source
var DefaultBudgets = Budgets{TimeoutSeconds: 1800}

DefaultBudgets are a fresh policy's run budgets: half an hour and no turn limit.

View Source
var DefaultHarnessImages = map[string]HarnessImage{
	"copilot-image": {Ref: "agentry-copilot:1.0.95", Artifact: "sha256:fd36c0e57ae6285ccd9cff306fbcdf114343c44f968ff2364fa7fd1a4dc4b7bf"},
	"codex-image":   {Ref: "ghcr.io/blaktron/agentry-codex:0.166.0-2026.10.30.4@sha256:95584d22ed7f426109fa09675c53efe0b311bac1fd582535437d7b4f4e99e06f"},
	"claude-image":  {Ref: "agentry-claude-code:2.1.296", Artifact: "sha512-OX/k/rpcthMqnFKOWcpNcbiLsMKtAjLOpQNJHlYiDCFUznWCIwdRTyl/p9SdHVrsrzZuPMCNqZjnpakIni6upw=="},
}

DefaultHarnessImages are the CLI's pinned harness images for the adapters beyond docker-agent, by adapter name, each by digest or by the artifact it is built from.

codex-image: agentry-dockerimages' Codex harness image, OpenAI's Codex CLI 0.166.0 release binary verified against OpenAI's signature, amd64 and arm64, signed keyless by that repository's codex workflow on main (agentry-cli's CI verifies this digest against that identity, scripts/verify-codex-image.sh). A Codex bump re-records the adapter's conformance before this pin moves (README "Bumping Codex" there).

claude-image: Claude Code built on this machine, never published: the artifact is the npm integrity of @anthropic-ai/claude-code at the tag's version, and the build (pkg/runner/harnessbuild) holds the native package it installs to the integrity it carries for that release. A bump adds the release there and re-records the adapter's conformance before this pin moves.

copilot-image: GitHub's Copilot CLI built on this machine, never published: the artifact is the SHA-256 of the release's SHA256SUMS.txt, which names each platform's musl download's checksum; GitHub signs neither, so the receipt says the image is pinned by checksum, not signed. The build (pkg/runner/harnessbuild) fetches that file, holds it to the artifact, and holds the daemon's platform's download to the checksum it names. A bump adds the release there and re-records the adapter's conformance before this pin moves.

Functions

func AgentryRegistry added in v0.6.1005

func AgentryRegistry(m Model) (string, error)

AgentryRegistry is the registry a provider-agentry model is paid through: model.baseUrl less AgentryInferencePath. The endpoint must be https, except on a loopback address, with no query or user info.

func BaseExecCommands

func BaseExecCommands() []string

BaseExecCommands returns the commands every machine provides, sorted.

func CheckContextWindow added in v0.7.9

func CheckContextWindow(tokens int64) error

CheckContextWindow refuses a context window outside the bounds; 0 is unset and passes.

func CopilotPlanOf

func CopilotPlanOf(allow []string) string

CopilotPlanOf is the plan a Copilot run's allowlist names, "" when it is not one CopilotProxyAllow makes.

func CopilotPlans

func CopilotPlans() []string

CopilotPlans lists the Copilot plans by the name setup takes: individual (Free, Pro, Pro+ and Max), business and enterprise.

func CopilotProxyAllow

func CopilotProxyAllow(plan string) ([]string, error)

CopilotProxyAllow is the proxy allowlist of a Copilot run on plan: GitHub's API and that plan's Copilot API host.

func CredentialKindOf

func CredentialKindOf(provider, key string) string

CredentialKindOf reads the kind of a credential from its shape: a subscription OAuth token for Anthropic by its prefix, an API key for everything else — a shape this build does not know included, the endpoint being the judge. Pure; records nothing. Setup and the desktop write its answer into apiKeyKind at store time, a form uses it to say what a credential can drive before anything is stored, the models listing to send an Anthropic token in the header shape it needs, and the engine to hold a resolved value against the plan's expectation.

func DefaultPath

func DefaultPath() (string, error)

DefaultPath is the operator policy under the runner home: $AGENTRY_RUNNER_HOME/policy.yaml when the home is relocated, else ~/.agentry/runner/policy.yaml (see Home).

func Home

func Home() (string, error)

Home is the runner home: $AGENTRY_RUNNER_HOME when set, else ~/.agentry/runner. Every path under the runner home derives from here, the policy's included: a caller that relocates the home relocates the policy with it.

func IsModelSignIn

func IsModelSignIn(kind string) bool

IsModelSignIn reports whether kind is a model sign-in: a plan the person holds, which a hosted run never uses and which reports tokens, never dollars.

func KeyEnv

func KeyEnv(hp HarnessPolicy, m Model) string

KeyEnv is the variable a run reads the model key from for an adapter: the harness block's, else the model's.

func KeyKind

func KeyKind(hp HarnessPolicy, m Model) string

KeyKind is what the credential a run resolves is expected to be: the harness block's apiKeyKind, else the model's; unset is api. One rule, beside KeyEnv and KeySource.

func KeySource

func KeySource(hp HarnessPolicy, m Model) string

KeySource is where that key comes from when the variable is unset: the harness block's apiKeySource, else the model's; "" and "env" both mean the environment only. One rule, so the adapters, the compiler's receipt line and doctor cannot disagree.

func NewestPathFor added in v0.7.4

func NewestPathFor(policyPath string) string

NewestPathFor is where the record of the newest harness images is for the policy file at policyPath: beside it.

func PathIn

func PathIn(home string) string

PathIn is the operator policy's path under a given runner home.

func PinnedByDigest

func PinnedByDigest(ref string) bool

PinnedByDigest says whether ref is an image reference pinned by digest, so a pull of it can only yield those bytes and it is safe to write after a FROM.

func PythonVersionOf added in v0.6.1009

func PythonVersionOf(ref string) string

PythonVersionOf is the Python version a runtime image holds: for the CLI's own two defaults the exact version they were measured to run (DefaultPythonVersion, DefaultPythonFallbackVersion), for any other image the line its tag begins with ("3.14" for 3.14-slim-trixie, read as 3.14.0 by a range check), or "" when the tag names none.

func ReadNewest added in v0.7.4

func ReadNewest(path string) (map[string]Newest, error)

ReadNewest reads the record at path. A missing file is an empty record; one that cannot be read or parsed is an error, which a caller takes as no record at all.

func ResolvConf

func ResolvConf(rs []string) []byte

ResolvConf is the resolv.conf naming rs, the policy's docker.resolvers: the one the runner binds over docker's wherever a container under a sandboxed runtime resolves host names.

func Save

func Save(path string, p *Policy) error

Save writes the policy back to path as generated YAML. Used by `agentry setup`; hand-written comments in an existing file are not preserved, and the header says so.

func SignInProvider

func SignInProvider(kind string) string

SignInProvider is the provider a model sign-in kind spends, "" for any other kind.

func SignInProxyAllow

func SignInProxyAllow(kind string) []string

SignInProxyAllow is the proxy allowlist a run paid by kind has by default (a Copilot run's on the individual plans), nil for a kind with no fixed endpoint (a key).

func SignInProxyAllowed

func SignInProxyAllowed(kind string, allow []string) (ok bool, want string)

SignInProxyAllowed reports whether allow is an allowlist a run paid by kind may have, and says what it must be when it is not: exactly the kind's endpoints, or for Copilot GitHub's API and one plan's Copilot API host. Any allowlist is allowed for a kind with no fixed endpoint.

func SignInSentence

func SignInSentence(kind string) string

SignInSentence is what every surface says when a model sign-in meets something only a key can do, for kind.

func SignInTokenRoute

func SignInTokenRoute(hp HarnessPolicy) string

SignInTokenRoute is the token route hp names, the default when it names none.

func SplitTagRef

func SplitTagRef(ref string) (registry, repository, tag string, ok bool)

SplitTagRef splits <registry>/<repository>:<tag>, the one shape images.clamavSignatures takes, answering ok false for any other.

func TriesNewest added in v0.7.4

func TriesNewest(adapterName string) bool

TriesNewest reports whether adapterName's image is built from its vendor's newest release first: Claude Code's and Codex's.

func WebSearchProviders

func WebSearchProviders() []string

WebSearchProviders is the names webSearch.provider admits besides none, sorted.

func WriteNewest added in v0.7.4

func WriteNewest(path, adapterName string, n Newest) error

WriteNewest sets adapterName's entry in the record at path, keeping the others. The file is staged beside itself and renamed over, so a run reading it meanwhile reads the old record or the new one.

Types

type BrowserPolicy

type BrowserPolicy struct {
	// AllowPublicWeb lets a browser whose scope is public reach any public
	// site, on ports 80 and 443. Default false: such a release is refused
	// at compile time, as "*" egress is.
	AllowPublicWeb bool `yaml:"allowPublicWeb,omitempty"`
}

BrowserPolicy is the operator's say over a release's browser. Its own key beside allowWildcardEgress: an operator may let a site tester test any public site and still refuse "*" egress to the tools container's fetch, or the reverse.

type Budgets

type Budgets struct {
	// TimeoutSeconds is the whole-run deadline (default 1800).
	TimeoutSeconds int `yaml:"timeoutSeconds"`
	// MaxTurns caps tool-call events (default 0, unlimited).
	MaxTurns int `yaml:"maxTurns"`
	// MaxCostUSD kills the run once the harness's reported running cost
	// exceeds this many US dollars (exit 16); 0 = unlimited. Enforcement
	// is only as good as the harness's usage events.
	MaxCostUSD float64 `yaml:"maxCostUsd"`
}

Budgets are the policy-default hard stops.

type DockerPolicy

type DockerPolicy struct {
	// Runtime names the daemon's OCI runtime (`docker run --runtime`) for a
	// run's containers: gVisor's "runsc" on a host that has it registered. With
	// Resolvers named it also holds the llm-proxy, the MCP server install proxy
	// and the relays, save a host-run harness's proxy and, where the docker
	// filter does not run, the relays; without them those three stay on the
	// daemon's default, because they resolve hosts through docker's embedded
	// DNS, which a sandbox does not reach. The gateway takes GatewayRuntime.
	// The receipt's runtime line names each class. Empty means the daemon's
	// default. A set value is enforced, not preferred: a daemon without it
	// refuses the run at the ensure step (exit 13) rather than falling back, so
	// the receipt's runtime line is never a claim the run did not have.
	Runtime string `yaml:"runtime,omitempty"`
	// GatewayRuntime names the runtime the gateway is created with: a second
	// registration of gVisor with `--host-uds=open`, since the gateway reaches
	// the run's docker filter through a bind-mounted host Unix socket, which
	// runsc without that flag does not open. It needs Runtime: the gateway is
	// never sandboxed while the QuickAgent's code is not. Empty leaves the
	// gateway on the daemon's default. Enforced like Runtime (exit 13).
	GatewayRuntime string `yaml:"gatewayRuntime,omitempty"`
	// Resolvers are the name servers the built-in Drafter's web tools resolve
	// through, by address, and, under Runtime, the llm-proxy, the MCP server
	// install proxy and the relays too: at most three, as a resolv.conf reads
	// them. A sandboxed runtime's own network stack does not reach docker's
	// embedded DNS on a user-defined network (as under gVisor), and `--dns`
	// only sets that server's upstream, so the runner writes these into a
	// resolv.conf of the run's own that the tools server reads in place of
	// docker's. They are the host's to name: the host's upstream resolvers,
	// never a loopback stub. Empty keeps docker's DNS, which a run on the
	// daemon's default reaches; a run of the web tools under a runtime with
	// none is refused (exit 11) rather than left to read nothing.
	Resolvers []string `yaml:"resolvers,omitempty"`
	// Limits bound every container the runner starts for a run. The engine also
	// drops every capability and sets no-new-privileges on each. A zero field
	// takes its default (Limits.WithDefaults). The gateway passes memory and
	// CPUs on to the tool and server containers it launches.
	Limits Limits `yaml:"limits,omitempty"`
}

ExecPolicy is the exec catalog. The manifest keeps declaring bare command names; the operator, not the manifest, says which apk package provides each on this machine — the same stance as mcpRegistries. A declared command the catalog does not carry is a plan-time refusal, never a run-time "absent". Busybox applets the runner image already has (sh, sed, sort, …) are catalogued as `busybox`, and BaseExecCommands are catalogued on every machine without an entry. DockerPolicy is the daemon-facing part of the policy.

func (DockerPolicy) SandboxesProxies

func (d DockerPolicy) SandboxesProxies() bool

SandboxesProxies says whether the proxies run under the policy's runtime: only where the host's name servers are named for them to read.

type ExecPolicy

type ExecPolicy struct {
	// Packages maps a command name to the apk package that provides it,
	// optionally pinned: `git` or `git=2.49.1-r0`. Alpine's index drops a
	// version once a security update replaces it, so a pin can turn an
	// example's every run into a failed image build; the build records
	// the resolved versions into the receipt either way.
	Packages map[string]string `yaml:"packages,omitempty"`
	// APKMirror replaces the runner image's Alpine repositories at exec
	// image build time (`<mirror>/v<release>/main` and `/community`), for
	// an air-gapped machine. Empty: the image's own /etc/apk/repositories.
	// This is build-time egress of the image build only; a run's network
	// posture is unchanged.
	APKMirror string `yaml:"apkMirror,omitempty"`
}

func (ExecPolicy) Package

func (e ExecPolicy) Package(command string) string

Package returns the apk package that provides a command: the catalog's entry, else busybox for a base command, else "" (not provided).

type File

type File struct {
	Path   string
	Source string
}

File is the operator policy file a run reads and how its path was chosen: what the receipt records beside the digest. Source is one of the receipt's values (receipt.PolicySource*).

func Resolve

func Resolve(flag string) (File, error)

Resolve is the operator policy a run reads: flag when --policy named one, else the runner home's policy.yaml — source "env" when AGENTRY_RUNNER_HOME relocated the home, "default" otherwise. The path is made absolute, so a record of it names one file.

type HarnessImage

type HarnessImage struct {
	// Ref is the image reference: <name>[:<tag>]@sha256:<digest> for a
	// published image, the local <name>:<tag> the build tags for a built
	// one.
	Ref string `yaml:"ref"`
	// Artifact is sha256:<64 hex> of the vendor artifact a built image is
	// made from (an npm package's integrity, a release download's
	// checksum); empty for a published image.
	Artifact string `yaml:"artifact,omitempty"`
}

HarnessImage pins one adapter's harness image: either a published image pinned by digest, or an image built on this machine from a vendor artifact, pinned by that artifact's hash. Never a bare tag.

func (HarnessImage) Pin

func (h HarnessImage) Pin() (by, value string)

Pin says how h is pinned and by what: the digest of a published image, the artifact hash of a built one, or the tag alone.

type HarnessPolicy

type HarnessPolicy struct {
	// Path is the executable to run instead of looking the harness up — on
	// PATH, then in its usual install locations (the native installer's
	// directory, a desktop app's bundled build; the adapter's WellKnownPaths).
	// A path set here wins over both, and one that does not exist is a refusal,
	// not a fallback.
	Path string `yaml:"path,omitempty"`
	// Model is the model id this harness is asked for (empty: model.name).
	// A harness that speaks its own vendor's API needs a model named in
	// that vendor's terms, which is not always the one model.name holds
	// for the default adapter.
	Model string `yaml:"model,omitempty"`
	// BaseURL points the harness at an endpoint that speaks its own API
	// (for claude, ANTHROPIC_BASE_URL). Empty: the harness's default
	// endpoint. The host must also be in model.proxyAllow, or the run
	// cannot reach it.
	BaseURL string `yaml:"baseUrl,omitempty"`
	// APIKeyEnv names the host env var holding this harness's key (empty:
	// model.apiKeyEnv). The value is read at run time and never stored.
	APIKeyEnv string `yaml:"apiKeyEnv,omitempty"`
	// APIKeyKind is as model.apiKeyKind, for this harness's key (empty:
	// model.apiKeyKind).
	APIKeyKind string `yaml:"apiKeyKind,omitempty"`
	// APIKeySource is as model.apiKeySource, for this harness's key
	// (empty: model.apiKeySource); the keychain entry is the model
	// provider's.
	APIKeySource string `yaml:"apiKeySource,omitempty"`
	// SignInTokenRoute is how a harness that spends a token-file model sign-in
	// reads its access token: auth-command (the default) has the harness read
	// the token file itself whenever it needs a token, so a renewal reaches it
	// mid-turn; restart starts the harness on the token of the moment and,
	// between turns, starts it again on a renewed one and resumes the
	// conversation (OpenAI's documented route for Codex's app-server). Only the
	// codex adapters read it.
	SignInTokenRoute string `yaml:"signInTokenRoute,omitempty"`
}

HarnessPolicy configures one host-run harness adapter — an adapter that drives the person's own installation of a harness rather than an image the runner pins.

type HostsPolicy

type HostsPolicy struct {
	// Allow, when set, is every network a target host's address may be in.
	Allow []string `yaml:"allow,omitempty"`
	// Deny is the networks a target host's address may never be in; it
	// wins over Allow.
	Deny []string `yaml:"deny,omitempty"`
}

HostsPolicy is the operator's rule for target hosts: IPv4 networks in CIDR form. Neither set, any address is reached but the ones a target host never is (loopback, link-local; targethost.CheckAddress).

func (HostsPolicy) Admits

func (h HostsPolicy) Admits(a netip.Addr) (bool, string)

Admits says whether the policy lets a run reach a, and why not when it does not.

type HybridAnalysisKey

type HybridAnalysisKey struct {
	// APIKeyEnv names the variable; empty is DefaultHybridKeyEnv.
	APIKeyEnv    string `yaml:"apiKeyEnv,omitempty"`
	APIKeySource string `yaml:"apiKeySource,omitempty"`
}

HybridAnalysisKey is where the Hybrid Analysis key comes from, as JudgeKey: the variable, else, with apiKeySource keyring, the OS keychain entry provider:hybrid-analysis (which the desktop writes).

func (HybridAnalysisKey) KeyEnv

func (h HybridAnalysisKey) KeyEnv() string

KeyEnv is the variable the Hybrid Analysis key is read from.

type Images

type Images struct {
	// Gateway is the docker/mcp-gateway image.
	Gateway string `yaml:"gateway"`
	// HarnessDockerAgent is the docker-agent harness image, as Load resolves
	// it. A policy file names it as harnessImages' docker-agent entry; the
	// older key harnessDockerAgent is still read, and naming both with
	// different images is refused. The default is pinned by digest. Former
	// generated defaults resolve to the current pin on load so an updated
	// adapter never runs the old default image. Other values are the
	// operator's and are kept.
	HarnessDockerAgent string `yaml:"harnessDockerAgent,omitempty"`
	// HarnessImages pins the harness image of each adapter that runs in a
	// container, by adapter name: by digest when published, by the vendor
	// artifact's hash when built on this machine, never by a tag (docker-agent
	// alone may be a tag, for a policy file written before its default was
	// pinned). Load moves the docker-agent entry to HarnessDockerAgent. Unset
	// entries take the CLI's defaults.
	HarnessImages map[string]HarnessImage `yaml:"harnessImages,omitempty"`

	// GoBuilder builds the local runner image.
	GoBuilder string `yaml:"goBuilder"`
	// Runner overrides the local runner image tag ("" = derived from the
	// CLI version).
	Runner string `yaml:"runner,omitempty"`
	// NodeRuntime / PythonRuntime install and run declared npm/PyPI MCP
	// servers. Empty resolves to the pinned defaults.
	NodeRuntime   string `yaml:"nodeRuntime,omitempty"`
	PythonRuntime string `yaml:"pythonRuntime,omitempty"`
	// PythonFallbackRuntime runs a PyPI server whose requires_python excludes
	// the default PythonRuntime's Python but admits this one, pinned by digest
	// ("" = DefaultPythonFallbackRuntime; see PythonFallbackImage). A policy
	// that sets PythonRuntime to its own image never falls back. The image's
	// tag begins with its Python line (3.14-...), which the choice reads.
	PythonFallbackRuntime string `yaml:"pythonFallbackRuntime,omitempty"`
	// Unsafe is the base Unsafe Mode builds a QuickAgent's exec image on,
	// pinned by digest ("" = DefaultUnsafeImage; see UnsafeImage). It
	// names an image and turns nothing on: only a client that passes
	// compile.Inputs.Unsafe uses Unsafe Mode, and no policy key or
	// `agentry run` flag does.
	Unsafe string `yaml:"unsafe,omitempty"`
	// Files is the files image the decode step builds its image on,
	// pinned by digest ("" = DefaultFilesImage; see FilesImage).
	Files string `yaml:"files,omitempty"`
	// ClamAVSignatures is the signature bundle the decode step refreshes,
	// <registry>/<repository>:<tag> ("" = DefaultClamAVSignatures; see
	// ClamAVSignaturesRef). A mirror must carry the clamav-db workflow's
	// signature, which is checked whatever the repository.
	ClamAVSignatures string `yaml:"clamavSignatures,omitempty"`
	// Hostlink is the host link's base image, pinned by digest ("" =
	// DefaultHostlinkImage; see HostlinkImage).
	Hostlink string `yaml:"hostlink,omitempty"`
	// Browser is the browser server's image, pinned by digest ("" =
	// DefaultBrowserImage; see BrowserImage).
	Browser string `yaml:"browser,omitempty"`
	// Coder is the Coding agent's toolchain image, pinned by digest ("" =
	// DefaultCoderImage; see CoderImage).
	Coder string `yaml:"coder,omitempty"`
	// Gog is the Assistant's Google Workspace server's image, pinned by
	// digest ("" = DefaultGogImage; see GogImage).
	Gog string `yaml:"gog,omitempty"`
	// MS365 is the Assistant's Microsoft 365 server's image, pinned by
	// digest ("" = DefaultMS365Image; see MS365Image).
	MS365 string `yaml:"ms365,omitempty"`
	// contains filtered or unexported fields
}

Images pins the container images. Digest-pinned refs (repo@sha256:…) are recommended in the generated default file.

func (Images) BrowserImage

func (i Images) BrowserImage() string

BrowserImage is the browser server's image this policy names: images.browser, else the CLI's pinned default, resolved at use as HostlinkImage is.

func (Images) ClamAVSignaturesRef

func (i Images) ClamAVSignaturesRef() string

ClamAVSignaturesRef is the signature bundle this policy names: images.clamavSignatures, else the CLI's default.

func (*Images) ClearNewest added in v0.7.4

func (i *Images) ClearNewest(adapterName string)

ClearNewest goes back to the tested pin for adapterName.

func (Images) CoderImage

func (i Images) CoderImage() string

CoderImage is the Coding agent's toolchain image this policy names: images.coder, else the CLI's pinned default, resolved at use as BrowserImage is.

func (Images) FilesImage

func (i Images) FilesImage() string

FilesImage is the files image this policy names: images.files, else the CLI's pinned default. Resolved at use, as UnsafeImage is, so a saved policy file never holds back a re-pin.

func (Images) GogImage added in v0.6.999

func (i Images) GogImage() string

GogImage is the Google Workspace server's image this policy names: images.gog, else the CLI's pinned default.

func (Images) HarnessImageFor

func (i Images) HarnessImageFor(adapterName string) (h HarnessImage, ok bool)

HarnessImageFor is the harness image adapterName runs in, from images.harnessImages (docker-agent's as Load resolved it into HarnessDockerAgent), else the newest release's image setup built (the record beside the policy file), else the CLI's tested default. ok is false for an adapter with none (a host adapter, which drives the person's own installation).

func (Images) HostlinkImage

func (i Images) HostlinkImage() string

HostlinkImage is the host link's base this policy names: images.hostlink, else the CLI's pinned default, resolved at use as FilesImage is.

func (Images) MS365Image added in v0.6.999

func (i Images) MS365Image() string

MS365Image is the Microsoft 365 server's image this policy names: images.ms365, else the CLI's pinned default.

func (Images) NewestRecord added in v0.7.4

func (i Images) NewestRecord(adapterName string) (Newest, bool)

NewestRecord is the record's entry for adapterName that Load or setup took, ok false when there is none.

func (Images) Pins added in v0.7.4

func (i Images) Pins(adapterName string) bool

Pins reports whether the policy file pins adapterName's harness image itself, which then is never replaced by a newer release.

func (Images) PythonFallbackImage added in v0.6.1009

func (i Images) PythonFallbackImage() string

PythonFallbackImage is the fallback Python runtime this policy names: images.pythonFallbackRuntime, else the CLI's pinned default. Resolved at use rather than written into a generated policy file, so a saved file never holds back a re-pin.

func (Images) PythonPinned added in v0.6.1009

func (i Images) PythonPinned() bool

PythonPinned says the policy runs PyPI servers on an image of its own choosing: images.pythonRuntime is anything but the CLI's default. Such a policy gets exactly that image for every PyPI server, with no fallback.

func (*Images) SetNewest added in v0.7.4

func (i *Images) SetNewest(adapterName string, n Newest)

SetNewest makes n's image the one adapterName runs in where the policy pins none itself, as setup does once it has built it.

func (Images) UnsafeImage

func (i Images) UnsafeImage() string

UnsafeImage is the Unsafe Mode base this policy names: images.unsafe, else the CLI's pinned default. Resolved at use rather than written into a generated policy file, so a saved file never holds back a re-pin.

type JudgeKey

type JudgeKey struct {
	// APIKeyEnv names the variable; empty is DefaultJudgeKeyEnv.
	APIKeyEnv string `yaml:"apiKeyEnv,omitempty"`
	// APIKeySource is "" or "env" (the environment only) or "keyring".
	APIKeySource string `yaml:"apiKeySource,omitempty"`
}

JudgeKey is where the person's own Jev key comes from. The value is never in this file: the variable, else, with apiKeySource keyring, the OS keychain entry provider:typesafe (which the desktop writes).

func (JudgeKey) KeyEnv

func (j JudgeKey) KeyEnv() string

KeyEnv is the variable the Jev key is read from.

type Limits

type Limits struct {
	Memory string `yaml:"memory,omitempty"`
	CPUs   int    `yaml:"cpus,omitempty"`
	Pids   int    `yaml:"pids,omitempty"`
}

Limits are the per-container resource bounds of a run: memory in docker's notation (`2g`), whole CPUs, and processes.

func (Limits) WithDefaults

func (l Limits) WithDefaults() Limits

WithDefaults fills every zero field with its default.

type MCPRegistries

type MCPRegistries struct {
	// NPM is the npm registry base URL (metadata + tarballs).
	NPM string `yaml:"npm,omitempty"`
	// PyPI is the PyPI base URL (JSON API at /pypi/, index at /simple).
	PyPI string `yaml:"pypi,omitempty"`
	// PyPIAllowSourceDists lets the builder fall back to source
	// distributions (which run the package's own build code inside the
	// runtime image at install time). Off by default: only wheels are
	// installed, for the declared server and its dependencies alike.
	// Turn on for a server that ships no wheel, knowing
	// what it costs.
	PyPIAllowSourceDists bool `yaml:"pypiAllowSourceDists,omitempty"`
}

MCPRegistries names the trusted repositories for declared MCP servers. Empty fields resolve to the public defaults at load time, so a policy file written before this block existed keeps working unchanged. They must be https: the install builder reaches them only through the install proxy, which tunnels TLS, with the registry's host (and the artifact hosts its metadata names for the pin) as its whole allowlist.

type MCPServersPolicy

type MCPServersPolicy struct {
	// AllowVulnerable lets a run proceed when the registry's gate rates an
	// advisory for a declared server version high or critical (the advisory's
	// own severity from a registry that serves no rating; ). Off by default:
	// such a run is refused (exit 11) unless --allow-vulnerable-mcp is given;
	// either override is recorded in the receipt.
	AllowVulnerable bool `yaml:"allowVulnerable,omitempty"`
}

MCPServersPolicy is the operator's stance on declared servers the registry knows to be vulnerable.

type Model

type Model struct {
	// Provider is the provider name: one of the setup table's
	// (anthropic, openai, google), "custom" for an OpenAI-compatible
	// endpoint of the operator's own (BaseURL required; the docker-agent
	// adapter renders it as the harness's openai client pointed at that
	// URL), or a provider name the harness itself knows.
	Provider string `yaml:"provider"`
	// Name is the model id.
	Name string `yaml:"name"`
	// APIKeyEnv names the host env var holding the API key. The value is
	// injected only into the agent container and disclosed in receipts.
	APIKeyEnv string `yaml:"apiKeyEnv"`
	// APIKeySource is where the key comes from when the variable is not
	// set: "" or "env" (the environment only) or "keyring" (the OS
	// keychain entry provider:<provider>, written by `agentry setup` or
	// the desktop). The variable wins whenever it is set;
	// the value is never in this file.
	APIKeySource string `yaml:"apiKeySource,omitempty"`
	// APIKeyKind is what the credential is, for the one provider whose keys
	// come in two kinds: "" or "api" (an API key, any harness) or
	// "subscription" (an Anthropic subscription OAuth token, which Anthropic
	// admits from Claude Code alone — the claude adapter passes it as
	// CLAUDE_CODE_OAUTH_TOKEN, the container harness refuses it). Written by
	// `agentry setup` or the desktop from the value's shape at store time; a
	// run checks the value it resolves against this and refuses a mismatch by
	// name.
	APIKeyKind string `yaml:"apiKeyKind,omitempty"`
	// BaseURL points provider-compatible adapters at a custom endpoint
	// (e.g. a local OpenAI-compatible server); empty = provider default.
	BaseURL string `yaml:"baseUrl,omitempty"`
	// ContextWindow is the model's context window in tokens, for a model the
	// harness cannot look up itself (an endpoint of the operator's own, or
	// any model outside the harness's catalogue). Without it such a harness
	// cannot compact a long conversation before the endpoint refuses it as
	// too long. 0 = the harness's own lookup.
	ContextWindow int64 `yaml:"contextWindow,omitempty"`
	// ProxyAllow is the llm-proxy CONNECT allowlist (host:port). This is
	// the ONLY egress the agent container has; it must cover the
	// model endpoint and nothing else.
	ProxyAllow []string `yaml:"proxyAllow"`
}

Model configures the operator-owned model endpoint (the key is always the operator's; packages never carry or suggest credentials).

type Newest added in v0.7.4

type Newest struct {
	// Checked is when the vendor was last asked for its newest release.
	Checked time.Time `json:"checked"`
	// Ref and Artifact are the image built from the newest release, as a
	// HarnessImage pins it. Empty when the newest release is the tested
	// one, or could not be used: the tested pin stands then.
	Ref      string `json:"ref,omitempty"`
	Artifact string `json:"artifact,omitempty"`
	// Version is the vendor's version of that release.
	Version string `json:"version,omitempty"`
	// Release is what the builder needs to build that release again, as
	// the builder writes it.
	Release json.RawMessage `json:"release,omitempty"`
	// Failed names the newest release that could not be used and why, for
	// the log and for the person asking; it is tried again at the next
	// check.
	Failed string `json:"failed,omitempty"`
}

Newest is one adapter's entry in that record.

func (Newest) Image added in v0.7.4

func (n Newest) Image() (h HarnessImage, ok bool)

Image is the harness image the entry records, ok false when it records none.

type Policy

type Policy struct {
	// PolicyVersion pins the schema ("1").
	PolicyVersion string `yaml:"policyVersion"`
	// Images pins every image the runner may pull or build.
	Images Images `yaml:"images"`
	// Model configures the LLM the default adapter drives.
	Model Model `yaml:"model"`
	// AllowWildcardEgress gates manifest `network.egress: "*"`.
	// Default false: a wildcard agent is refused at compile time.
	AllowWildcardEgress bool `yaml:"allowWildcardEgress"`
	// AllowPersistentReleases lets a persistent release run as a persistent
	// agent on this computer: one installed from the registry, or an
	// author's own folder. Unset is true; false refuses every persistent
	// agent but the ones built into Agentry.
	AllowPersistentReleases *bool `yaml:"allowPersistentReleases,omitempty"`
	// AllowMessengers lets the person add a messenger (Telegram and the
	// others) to a persistent agent, so they can talk to it from there.
	// Unset is true; false refuses every messenger, and an agent that has
	// one runs without it.
	AllowMessengers *bool `yaml:"allowMessengers,omitempty"`
	// MessengerKinds, when set, are the only messengers allowed, by name
	// (telegram). Unset allows every one this build knows.
	MessengerKinds []string `yaml:"messengerKinds,omitempty"`
	// Browser governs a release's browser (capabilities.browser):
	// whether one may reach any public site.
	Browser BrowserPolicy `yaml:"browser,omitempty"`
	// SecretSource is where declared secret values are resolved from.
	SecretSource SecretSource `yaml:"secretSource"`
	// DataAccessServers maps a manifest dataAccess category to operator
	// catalog server-entry YAML files to attach for agents declaring it
	// (default empty).
	DataAccessServers map[string][]string `yaml:"dataAccessServers,omitempty"`
	// Budgets are the default hard stops. A run's flags override them, and
	// a built-in package run on this computer starts from a longer timeout
	// of its own (localrun.Builtin.LocalBudgets).
	Budgets Budgets `yaml:"budgets"`
	// Sessions caps interactive sessions.
	Sessions Sessions `yaml:"sessions"`
	// Profiles configures MCP-profile behavior.
	Profiles Profiles `yaml:"profiles,omitempty"`
	// MCPRegistries is where declared capabilities.mcpServers resolve:
	// npm and PyPI by default, private mirrors here.
	MCPRegistries MCPRegistries `yaml:"mcpRegistries,omitempty"`
	// MCPServers governs the registry's vulnerability verdict on declared
	// servers.
	MCPServers MCPServersPolicy `yaml:"mcpServers,omitempty"`
	// Harness holds per-adapter settings for the adapters that run the
	// person's own installation of a harness, keyed by adapter name.
	Harness map[string]HarnessPolicy `yaml:"harness,omitempty"`
	// Exec is the operator's exec catalog: which binaries this machine
	// provides to a QuickAgent that declares `exec: {commands}`, and from
	// where.
	Exec ExecPolicy `yaml:"exec,omitempty"`
	// Docker is how the runner drives the daemon beyond the images: the
	// OCI runtime a run's containers are created with.
	Docker DockerPolicy `yaml:"docker,omitempty"`
	// Judge names where the person's own AI Review (TypeSafe Jev) key comes
	// from, for local work that needs a scan: a draft made on this computer.
	// Unset takes $TYPESAFE_API_KEY from the environment.
	Judge JudgeKey `yaml:"judge,omitempty"`
	// WebSearch names the person's own search provider and where its key
	// comes from, for a local draft's web_search. Unset, a local draft
	// has no web search (its web_read and registry_search still work).
	WebSearch WebSearchKey `yaml:"webSearch,omitempty"`
	// Hosts narrows the target hosts a run may reach: any address the person
	// names is reachable but loopback and link-local, and these lists narrow
	// the rest.
	Hosts HostsPolicy `yaml:"hosts,omitempty"`
	// HybridAnalysis names where the Hybrid Analysis key comes from, with which
	// the risky types among a run's inputs are looked up by SHA-256 Unset takes
	// $HYBRID_API_KEY from the environment, as a sandbox host hands the
	// platform's; no key, no lookup, and the receipt says so.
	HybridAnalysis HybridAnalysisKey `yaml:"hybridAnalysis,omitempty"`
	// MalwareCheck turns on the malware check of a local run's inputs:
	// ClamAV, and the Hybrid Analysis lookup when a key is set. Unset or
	// false, a local run checks only the executables among its inputs, and
	// only when the QuickAgent declares commands. A sandbox host's runs are
	// always checked, whatever this says.
	MalwareCheck *bool `yaml:"malwareCheck,omitempty"`
}

Policy is the whole operator policy file (closed schema; unknown keys are errors so a typo cannot silently disable a control).

func Default

func Default() *Policy

func EnsureDefault

func EnsureDefault(path string) (*Policy, string, error)

EnsureDefault writes the commented default policy file if path does not exist, then loads it. First `agentry run` on a machine goes through here, so the file the operator later edits is the file that ran.

Two first runs on a fresh runner home (a CLI run and a desktop run started together) both come here: the default is staged beside path and linked into place only if no file is there yet, so neither ever reads it half-written and a policy the operator wrote meanwhile is never replaced.

func Load

func Load(path string) (*Policy, string, error)

Load reads and validates a policy file, also returning the sha256 of the exact bytes read (the plan's policySha256). Strict decoding: unknown keys are errors.

func (*Policy) KeepProfilesByDefault

func (p *Policy) KeepProfilesByDefault() bool

KeepProfilesByDefault resolves the default keep choice (unset → true: authenticated resources are the point of profiles; discarding is the explicit choice).

func (*Policy) MalwareCheckOn

func (p *Policy) MalwareCheckOn() bool

MalwareCheckOn says whether the policy turns the whole malware check on for this computer's runs (unset → off).

func (*Policy) MessengerAllowed added in v0.7.12

func (p *Policy) MessengerAllowed(kind string) (bool, string)

MessengerAllowed says whether the policy lets a persistent agent be reached on the messenger kind, and why not.

func (*Policy) PersistentReleasesAllowed added in v0.6.1015

func (p *Policy) PersistentReleasesAllowed() bool

PersistentReleasesAllowed says whether the policy lets a persistent release that is not built into Agentry run as a persistent agent (unset → allowed).

func (*Policy) RunnerImageTag

func (p *Policy) RunnerImageTag(version string) string

RunnerImageTag returns the local runner image tag: the policy override, or a tag derived from version — which every client passes as runnerimage.ContentVersion(), so the CLI and the desktop app share one image for one embedded build context.

func (*Policy) Validate

func (p *Policy) Validate() error

Validate enforces the closed vocabulary. It runs at load time and again (via Load) before every compile, so a hand-edited policy fails before a container starts, with the field named.

type Profiles

type Profiles struct {
	// KeepByDefault is the default completion choice when neither the
	// run flag nor guided setup decided: keep (true) or remove. A
	// pointer so a policy file written before this field existed reads
	// as "unset" (→ true), not as false.
	KeepByDefault *bool `yaml:"keepByDefault,omitempty"`
}

Profiles is the MCP-profile policy block.

type SecretSource

type SecretSource struct {
	// Mode is "env" (host environment) or "envFile".
	Mode string `yaml:"mode"`
	// EnvFile is the dotenv path for mode envFile.
	EnvFile string `yaml:"envFile,omitempty"`
}

SecretSource resolves declared secret names to values.

type Sessions

type Sessions struct {
	// IdleTimeoutSeconds ends a session after this much silence from the
	// user (default 900).
	IdleTimeoutSeconds int `yaml:"idleTimeoutSeconds"`
	// MaxWallSeconds is the whole-session deadline (default 7200).
	MaxWallSeconds int `yaml:"maxWallSeconds"`
	// MaxUserTurns caps user messages per session (default 200; 0 = unlimited).
	MaxUserTurns int `yaml:"maxUserTurns"`
}

Sessions are the interactive-session caps. A manifest's interactive.idleTimeoutSeconds may ask for less idle time, never more.

type WebSearchKey

type WebSearchKey struct {
	// Provider is "" or "none" (no search), or one of WebSearchProviders.
	Provider string `yaml:"provider,omitempty"`
	// APIKeyEnv names the variable; empty is the provider's own
	// (DefaultWebSearchKeyEnv for youcom, BraveSearchKeyEnv for brave, and
	// so on through webSearchProviders).
	APIKeyEnv    string `yaml:"apiKeyEnv,omitempty"`
	APIKeySource string `yaml:"apiKeySource,omitempty"`
}

WebSearchKey is the person's own search provider, and where its key comes from, as JudgeKey (keychain entry provider:<provider>).

func (WebSearchKey) KeyEnv

func (w WebSearchKey) KeyEnv() string

KeyEnv is the variable the search key is read from: the one the policy names, else the provider's own, so a You.com key never serves Brave.

func (WebSearchKey) On

func (w WebSearchKey) On() bool

On reports whether a search provider is named.

func (WebSearchKey) ProviderName

func (w WebSearchKey) ProviderName() string

ProviderName is the provider as a person knows it ("Brave", "Tavily").

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL