View Markdown

agentrc Specification

Version: 0.1.0-draft.4
Status: Working Draft
Editor: Adeel Ahmad
Date: 2026-06-30
Audience: agent developers, platform engineers, security engineers, registry maintainers, runner implementers, compliance reviewers

1. Status of this document

This document is a working draft of the agentrc Agentfile and Package Specification.

This specification defines:

a declarative file format for a single AI agent, called an Agentfile;
a lockfile format for resolved agent dependencies;
an OCI-compatible package model for distributing agents;
a security-boundary declaration model for filesystems, network egress, credentials, tools, functions, skills, MCP servers, rate limits, and audit;
conformance profiles for tools, policy, package distribution, and runners.

This specification does not define a runtime. It does not require a particular sandbox, model provider, agent framework, cloud provider, or tool-calling transport.

The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL are to be interpreted as normative requirement levels.

2. Abstract

agentrc defines a portable declaration and packaging format for AI agents.

The Agentfile declares what an agent is and what it is allowed to request. The agent package carries the Agentfile, lockfile, policy, tools, functions, skills, metadata, and optional source artifacts. Compatible runners execute the package and enforce the declared boundaries.

The intended result is separation of concerns:

Concern	Owned by
Agent declaration	Agentfile
Dependency pinning	agentrc.lock
Package distribution	OCI-compatible registry
Security and governance intent	Policy and boundary declarations
Execution and isolation	Compatible runner
Cloud/runtime-specific enforcement	Runner implementation
Multi-agent orchestration	Future workflow companion spec

agentrc allows developers to define an agent once, security teams to review it before execution, registries to share it as a reusable artifact, and runners to execute it without requiring the agent to be rewritten for a specific runtime or cloud.

3. Design goals

The design goals are:

Declarative single-agent format — one reviewable file describes one agent.
Runtime neutrality — the package is not bound to Docker, Kubernetes, gVisor, Firecracker, microsandbox, a managed cloud, or any specific local runner.
Security by declaration — access to tools, credentials, networks, mounts, functions, skills, and sub-systems is explicit.
Governance portability — policy travels with the package and can be evaluated before execution.
Registry sharing — agents, bases, skills, tools, toolsets, and policies can be distributed using content-addressed registries.
Reproducibility — resolved dependencies and digests are captured in a lockfile.
Profile-based conformance — implementations can support the core Agentfile without implementing every optional execution profile.
Extensibility — multi-agent workflows, tool projection, and runner-specific enforcement are layered profiles, not hard-coded into the core format.

4. Non-goals

agentrc does not define:

a new runtime;
a new sandboxing technology;
a new model API;
a new agent framework;
a new wire protocol for tool calls;
a replacement for MCP or A2A;
a replacement for Cedar, OCI, OpenTelemetry, Sigstore, SLSA, Docker, Kubernetes, gVisor, Firecracker, or cloud runtimes;
a full workflow language in the single-agent format;
cloud infrastructure provisioning;
a central proprietary registry.

agentrc packages declare requirements. Compatible runners decide whether and how they can satisfy those requirements.

5. Core terminology

5.1 Agent

An agent is a software unit with an entrypoint, capabilities, dependencies, and declared boundaries.

5.2 Agentfile

An Agentfile is the source declaration for a single agent package.

5.3 Agent package

An agent package is the built artifact produced from an Agentfile. It contains the Agentfile, lockfile, policy, metadata, and supporting artifacts required to instantiate the agent.

5.4 Runner

A runner is an implementation that can execute an agentrc package. Examples include a local CLI runner, a container runner, a gVisor-backed runner, a microVM runner, a serverless runner, or a managed cloud runner.

A runner is outside the core Agentfile format. A runner may claim conformance to one or more profiles defined by this specification.

5.5 Capability

A capability is any declared thing the agent can use to read, write, call, invoke, or affect the outside world. Tools, functions, MCP servers, mounts, URLs, credentials, skills, memories, and delegated agents are capabilities.

5.6 Boundary

A boundary is a declared limit on a capability. Boundaries include filesystem access, network egress, credential access, tool permission, rate limits, timeouts, resource limits, and audit requirements.

5.7 Policy

A policy is a machine-evaluable rule set governing a capability request. The default agentrc policy profile is Cedar.

5.8 Registry

A registry is a content-addressed distribution system that stores agentrc packages or package components. OCI registries are the default distribution mechanism.

5.9 Profile

A profile is a named subset of conformance requirements. agentrc uses profiles so the specification can remain neutral while still allowing concrete implementations to prove compatibility.

6. Layering model

agentrc is divided into six layers.

Layer	Purpose	Defined here?
Core Agentfile	Single-agent declaration grammar and semantics	Yes
Security profile	Boundary, policy, credential, audit semantics	Yes
Package profile	Lockfile and OCI package layout	Yes
Registry profile	Pull/push/inspect/verify expectations	Yes
Runner profile	Execution and enforcement obligations for compatible runners	Limited; profile only
Workflow profile	Multi-agent state-machine orchestration	Future companion draft

The core specification deliberately stops at the package boundary. Execution is performed by runners.

7. Agentfile syntax model

An Agentfile is a line-oriented text file using Dockerfile-like directives.

Rules:

Blank lines are ignored.
Lines whose first non-whitespace character is # are comments.
Inline comments MAY appear after whitespace followed by #.
Directive names are uppercase ASCII tokens.
Arguments are whitespace-separated unless a future profile defines quoting semantics.
POLICY and SOP open multi-line blocks closed by END.
Unknown directives MUST fail validation unless explicitly placed in an extension namespace profile.

A syntax marker MAY be carried as a comment so older parsers can ignore it:

# syntax=agentrc.agentfile/v0.1

8. Minimal valid Agentfile

# syntax=agentrc.agentfile/v0.1

AGENT hello-local
CMD strands run --agent hello-local
TOOL utcp:file_read
AUDIT basic

POLICY
  permit(
    principal == AgentRC::Agent::"hello-local",
    action in [AgentRC::Action::"tool.invoke"],
    resource == AgentRC::Tool::"file_read"
  );
END

For local development, a runner MAY infer an agent identity from FROM or the package reference if AGENT is absent. Published packages SHOULD declare AGENT explicitly.

9. Agentfile directives

This section defines the full directive vocabulary. Only a minimal subset is normative core for v0.1 — AGENT, FROM, CMD, TOOL, MOUNT, CRED, URL, POLICY, and AUDIT. Every other directive below belongs to an optional profile; see the Core profile for the full classification table. Implementations MAY parse additional directives under extension profiles, but they MUST NOT silently reinterpret core directives, and an implementation MUST publish which profiles it actually supports rather than implying that every recognized directive is enforced.

The directives in §9.13 and §9.21–§9.25 (BIND, SLICE, IMAGE, ISOLATION, BROKER, BACKEND) plus PLUGIN (§9.15) are placement concerns, not capability concerns. They describe where and how an agent runs rather than what it is. To preserve content-addressed, signable identity, these SHOULD be carried in a separate Run Manifest chosen by the operator or runner and SHOULD NOT contribute to the package digest. See §24 Q1.

9.1 `AGENT`

Declares the stable identity of the agent.

AGENT code-reviewer

Published packages SHOULD include AGENT. The value SHOULD be a lowercase DNS-label-compatible identifier.

9.2 `FROM`

Declares a base package or base environment.

FROM ghcr.io/org/base-agent:1.4
FROM python:3.11-slim
FROM scratch

FROM MAY refer to an agentrc agent package, an OCI image, or scratch.

If the reference is an agentrc package, inheritance rules apply. If the reference is an ordinary OCI image, it is treated as a base execution environment and no agent inheritance is implied.

A child package MUST NOT weaken inherited security ceilings from a parent agentrc package.

9.3 `SHELL`

Declares the agent framework, shell, or adapter expected by the agent entrypoint.

SHELL strands
SHELL strands:shell@2026.5
SHELL langchain
SHELL crewai

SHELL is not a runtime. It is a framework or command adapter hint. A runner that does not support the requested shell MUST report an unsupported-shell error.

9.4 `CMD`

Declares the command used to start the agent.

CMD strands run --agent code-reviewer
CMD claude --print
CMD python -m agent.main

The command is interpreted inside the execution environment chosen by the runner.

9.5 `TOOL`

Declares a tool capability.

TOOL utcp:file_read
TOOL utcp:shell
TOOL strands:current_time
TOOL mcp:github.get_issue

A tool reference SHOULD identify a namespace and tool name. Tool metadata SHOULD include input schema, output schema, version, digest, risk tier, and provenance.

agentrc does not invent a tool-calling transport. Tools described and invoked through the Universal Tool Calling Protocol (UTCP) use the utcp: namespace, and SHOULD follow the UTCP specification for their tool descriptions. Tools provided over the Model Context Protocol use the mcp: namespace (see §9.10).

Declaring a tool does not automatically grant use of the tool unless the active security profile allows it. Under deny-by-default security, the tool must also be permitted by policy.

9.6 `TOOLSET`

Declares a bundle of tools.

TOOLSET strands:workspace
TOOLSET registry://tools.example.com/platform-safe@sha256:...

A toolset MUST resolve to a deterministic list of tool references during lockfile generation.

9.7 `FUNCTION`

Declares a typed function capability.

FUNCTION ./functions/review.py:summarize_diff
FUNCTION summarize_meeting

A function reference MAY be a local module path and symbol, or a symbolic name resolved by a runner/framework adapter.

Function metadata SHOULD include input schema, output schema, version, digest, and postcondition metadata where available.

9.8 `SKILL`

Declares a skill bundle.

SKILL pr-review
SKILL ./skills/incident-sop
SKILL ghcr.io/org/skills/pii-review:1.2

A skill SHOULD contain a SKILL.md file. Skill metadata SHOULD include name, version, description, license, digest, and provenance.

9.9 `SERVER`

Declares an external server dependency, typically an MCP server or API-backed tool server.

SERVER github https://api.github.com
SERVER internal https://tools.internal.example/mcp

Calls to declared servers remain subject to network and policy boundaries.

9.10 `MCP`

Declares an MCP dependency by logical name or registry reference.

MCP github
MCP registry://modelcontextprotocol/filesystem@1.0.2

MCP dependencies follow the Model Context Protocol (MCP) specification. agentrc does not replace or re-specify MCP; it declares the dependency and governs it.

An MCP declaration grants no ambient access. The runner must still apply policy, credentials, and network boundaries to MCP calls.

9.11 `URL`

Declares a network destination that the package requests.

URL https://api.github.com
URL https://registry.npmjs.org

Network access is deny-by-default under the Security Declaration Profile. A declared URL is a requested boundary, not an entitlement. The runner MUST fail closed if required egress policy cannot be enforced, unless the operator explicitly overrides the package outside the package itself.

9.12 `CRED`

Declares a credential or secret reference.

agentrc adopts the host-scoped placeholder-substitution secret model defined by microsandbox. A secret is bound to a source and to one or more allowed hosts. The real value MUST NOT enter the agent’s execution environment: the agent only ever sees a placeholder, and a conforming runner swaps the placeholder for the real value at the network layer, only for outbound requests to the secret’s allowed hosts.

CRED github_token env:GITHUB_TOKEN host:api.github.com
CRED openai_key  env:OPENAI_API_KEY host:api.openai.com
CRED stripe_key  env:STRIPE_KEY     host:*.stripe.com inject:header
CRED db_password vault://secret/data/prod/db#password host:db.internal.example
CRED github_token keyring:github_token host:api.github.com

Syntax:

CRED <name> <source> host:<host-or-pattern> [host:<host-or-pattern> ...] [inject:header|query]

Part	Meaning
`<name>`	Logical secret name. The agent environment sees a placeholder (e.g. `$<NAME>`), never the value.
`env:<VAR>`	Source the value from an environment variable on the host resolving the package.
`vault://<path>#<key>`	Source the value from a Vault-like backend.
`keyring:<key>`	Source the value from an OS/user keyring.
`host:<host>`	An allowed destination host the secret may be substituted into. Patterns such as `*.stripe.com` are permitted. Requests to any other host MUST NOT receive the value.
`inject:header` \| `inject:query`	Where the runner injects the secret on an allowed request. Defaults to `header`.

Rules:

A package MUST NOT contain plaintext secret values.
The secret value MUST NOT be exposed to agent code, tools, the filesystem, environment dumps, traces, or audit — only a placeholder is visible inside the sandbox.
A runner MUST substitute the value only for outbound requests to a declared allowed host; a secret with no host: binding MUST NOT be substituted into any request.
Runners MUST redact credential values from logs, audit events, lockfiles, and package metadata.
If a runner cannot enforce host-scoped substitution for a required secret, it MUST fail closed rather than expose the value to the sandbox.

For backward compatibility a runner MAY accept a host-less CRED <name> <source>, but it SHOULD warn, because an unbound secret cannot be safely placeholder-substituted.

9.13 `BIND`

Declares host-to-agent filesystem binding intent.

BIND ./repo /workspace copy
BIND ./out /output direct
BIND ./data /data ro

Syntax:

BIND <source> <target> <mode>

Recommended modes:

Mode	Meaning
`copy`	Copy source into the execution environment before start
`direct`	Expose source directly if supported by runner
`ro`	Read-only mount
`rw`	Read-write mount

Compatibility note: early implementations may accept BIND <source> <target> and normalize it to copy.

9.14 `MOUNT`

Declares an internal mount path and mutability.

MOUNT /workspace rw
MOUNT /data ro

MOUNT is a sandbox-facing boundary. BIND describes source-to-target mapping; MOUNT describes the path the agent expects to see. Runners MAY satisfy a MOUNT by copy, bind mount, volume, object store mount, memory filesystem, or another substrate-specific mechanism.

9.15 `PLUGIN`

Declares an execution capability module requested from the runner.

PLUGIN network
PLUGIN filesystem
PLUGIN secrets

PLUGIN is not core execution semantics. It is a runner capability requirement. A runner that cannot provide a required plugin MUST fail with an unsupported-plugin error.

9.16 `POLICY` block

Declares inline policy source.

POLICY
  permit(
    principal == AgentRC::Agent::"code-reviewer",
    action in [AgentRC::Action::"tool.invoke"],
    resource == AgentRC::Tool::"file_read"
  );
END

The default policy language is Cedar. A runner that claims Cedar support MUST evaluate with Cedar semantics, not string matching.

9.17 `ALLOW`, `DENY`, and `RATELIMIT`

Declare shorthand policy rules.

ALLOW invoke utcp:file_read
DENY invoke utcp:shell
RATELIMIT file_write 20/hour

These directives are convenience syntax. A compiler MAY lower them into the active policy profile. If both an allow and deny match the same request, deny MUST win.

9.18 `AUDIT`

Declares audit expectations.

AUDIT basic
AUDIT all
AUDIT compliance

Recommended values:

Value	Meaning
`off`	No package-level audit requirement
`basic`	Invocation and lifecycle audit
`all`	Tool/function/policy/credential/rate-limit audit
`compliance`	Structured, exportable audit suitable for review

If audit is required and the runner cannot produce audit events, the runner MUST fail closed.

9.19 `TIMEOUT`

Declares a default execution timeout in seconds.

TIMEOUT 30

9.20 `LIMIT`

Declares a named resource, output, or behavioral limit.

LIMIT max_output 1048576
LIMIT tool_calls 100
LIMIT network_requests 50/min

A runner MUST report unsupported required limits. A runner SHOULD fail closed for security-relevant limits it cannot enforce.

9.21 `SLICE`

Declares resource shape requirements.

SLICE cpu=2 mem=2048

SLICE is a runner resource hint/profile directive. It does not require agentrc to define resource isolation itself.

9.22 `IMAGE`

Declares an image expected by a runner or package builder.

IMAGE ghcr.io/agentrc/dev-sandbox:1.0

IMAGE is an execution/package hint. It MUST NOT be interpreted as making agentrc a runtime.

9.23 `ISOLATION`

Declares a requested isolation profile.

ISOLATION local
ISOLATION container
ISOLATION microvm
ISOLATION ssh

ISOLATION is a compatibility directive for current implementations. In the core specification, execution placement SHOULD be selected by the operator or runner. If ISOLATION appears in an Agentfile, it is a requested runner profile, not an implementation mandate.

A future version may move placement into a separate run manifest.

9.24 `BROKER`

Declares a secret broker family.

BROKER vault
BROKER local

A broker is a credential-resolution implementation detail. The Agentfile declares the requested broker type, but the runner controls actual resolution.

9.25 `BACKEND`

Declares a remote backend or execution endpoint.

BACKEND ssh://runner.internal.example

BACKEND is a runner/implementation extension. Published portable packages SHOULD avoid relying on a single backend unless the package is intentionally environment-specific.

9.26 `TRACE`

Declares trace emission or trace capture preference.

TRACE on
TRACE otlp://collector.internal:4317

Trace values MUST NOT contain secrets.

9.27 `MEMORY`

Declares a bounded memory or state surface.

MEMORY writing ./schemas/writing.schema.json schema:WritingMemory mode:rw

Memory declarations SHOULD include a schema and mode. Runners MUST apply policy and audit semantics to memory read/write operations when supported.

9.28 `OPTIMIZER`

Declares an optimizer hook or optimization strategy.

OPTIMIZER textgrad

Optimizers are optional. A runner/compiler that does not support the optimizer MUST report it clearly. Optimizer outputs MUST NOT silently weaken policy or boundaries.

9.29 `HEALTHCHECK`

Declares a health probe.

HEALTHCHECK --interval=30s --timeout=5s CMD utcp:ping

A runner MAY use health checks for lifecycle management. A runner that ignores health checks SHOULD report that the directive is unsupported.

9.30 `SOP`

Declares a Standard Operating Procedure — a reusable, natural-language instruction set that guides the agent through a multi-step task. agentrc adopts the Agent SOP model from Strands Agents: SOPs are markdown instruction sets with parameterized inputs and RFC 2119 constraints (MUST / SHOULD / MAY) that steer agent behavior without rigid scripting.

A SOP may be referenced from a file or registry, or embedded inline in the Agentfile as a block closed by END:

# Reference an external SOP (markdown, or an Agent Skill SKILL.md bundle)
SOP ./sops/code-review.md
SOP ghcr.io/org/sops/incident-response:1.2

# Or embed an SOP directly in the Agentfile
SOP code-review
  ## Overview
  Review a pull request for correctness and security.

  ## Parameters
  - **diff** (required): the unified diff to review

  ## Steps
  ### 1. Triage
  - You MUST read the full diff before commenting.
  - You MUST NOT approve if any required check is failing.

  ### 2. Report
  - You SHOULD group findings by severity.
  - You MAY suggest concrete patches.
END

The two forms are distinguished by the argument: an SOP line whose argument is a file path or registry/OCI reference (it contains /, ://, or a file extension) is the single-line reference form; otherwise the argument is a bare name and the directive opens a block closed by a line containing only END.

An SOP SHOULD follow the Agent SOP section structure (Overview, Parameters, Steps with constraints, optional Examples and Troubleshooting). Because Agent SOPs are distributable as the open SKILL.md Agent Skills format, an SOP MAY also be packaged and resolved as a SKILL (§9.8).

Semantics:

Embedded SOP blocks are captured verbatim, exactly like POLICY blocks, and MUST NOT be parsed as Agentfile directives.
SOP content is instruction, not capability or authority: an SOP MUST NOT grant access that policy and boundary declarations do not already permit. Instructions never widen the security ceiling.
SOP references SHOULD be pinned by digest in the lockfile so the embedded guidance is reproducible.
A runner that injects SOP instructions into the agent’s context SHOULD record which SOPs were active when AUDIT requires it.

10. Security model

agentrc security is declarative and reviewable.

The Agentfile declares requested boundaries; a conforming runner enforces supported boundaries or fails closed.

Principles:

No ambient authority — tools, credentials, files, networks, functions, skills, and servers are declared explicitly.
Deny by default — undeclared access is not granted under the Security Declaration Profile.
Fail closed — unsupported required security controls cause failure, not silent weakening.
Deny wins — forbids override permits.
Secrets are host-scoped references — no plaintext secret values appear in source, lockfile, package, logs, or audit. Following microsandbox, a secret value never enters the sandbox; the agent sees a placeholder and the runner substitutes the real value only at the network layer for the secret’s declared allowed hosts.
Policy travels with package — policy source or compiled policy profile is content-addressed and included in the package.
Inheritance tightens — child packages cannot weaken inherited ceilings.
Operator override is explicit — any override is outside the package and auditable.

11. Cedar policy profile

The default agentrc policy profile is Cedar, the open-source authorization policy language created by AWS. agentrc adopts Cedar’s syntax and semantics as its policy lingua franca rather than defining a new policy language; policies are written in Cedar and evaluated with a Cedar-compatible evaluator.

A Cedar request evaluates:

Cedar element	agentrc meaning
Principal	agent identity, caller, or delegated agent
Action	operation such as `tool.invoke`, `function.invoke`, `cred.resolve`, `network.egress`
Resource	tool, function, skill, host, path, credential, memory, server, or agent
Context	request attributes such as path, URL, destination host, caller, rate bucket, or mount mode

Recommended namespace examples:

AgentRC::Agent::"code-reviewer"
AgentRC::Tool::"file_read"
AgentRC::Function::"summarize_meeting"
AgentRC::Skill::"pr-review"
AgentRC::Credential::"github_token"
AgentRC::Host::"api.github.com"
AgentRC::Path::"/workspace"
AgentRC::Action::"tool.invoke"
AgentRC::Action::"function.invoke"
AgentRC::Action::"cred.resolve"
AgentRC::Action::"network.egress"

A runner that claims support for the Cedar profile MUST:

parse Cedar policy with a Cedar-compatible evaluator;
deny on parse or evaluation failure;
enforce forbid-overrides-permit behavior;
include request context in evaluation;
record allow and deny decisions when audit is required.

12. Agent package model

An agentrc package is a content-addressed bundle containing:

Agentfile;
agentrc.lock;
agent metadata/config;
policy sources or compiled policy profile;
tool metadata or bundled tools;
function code or function references;
skill bundles;
optional source layer;
optional framework/runtime adapter metadata;
provenance and signature metadata where available.

The package is a recipe for instantiating an agent, not a live VM snapshot and not a specific runtime instance.

13. Lockfile model

The lockfile pins resolved artifacts.

A lockfile SHOULD contain:

{
  "version": "1",
  "agentfile_hash": "sha256-or-short-hash",
  "base_image": {
    "registry": "ghcr.io",
    "name": "org/base-agent",
    "tag": "1.0",
    "digest": "sha256:..."
  },
  "tools": [
    {
      "name": "utcp:file_read",
      "version": "1.0.0",
      "schema_hash": "sha256:...",
      "source": "registry://tools/file_read",
      "digest": "sha256:..."
    }
  ],
  "functions": [
    {
      "path": "./functions/review.py:summarize_diff",
      "hash": "sha256:...",
      "type_hint_digest": "sha256:...",
      "source": "local",
      "version": ""
    }
  ],
  "skills": [
    {
      "name": "pr-review",
      "version": "2.1.0",
      "hash": "sha256:...",
      "source": "./skills/pr-review"
    }
  ],
  "sops": [
    {
      "name": "pr-review",
      "version": "1.0.0",
      "hash": "sha256:...",
      "source": "inline"
    }
  ],
  "policy_hash": "sha256:...",
  "credential_names": ["github_token"],
  "timestamp": "2026-06-30T00:00:00Z"
}

A lockfile MUST NOT contain credential values.

14. OCI package profile

agentrc packages SHOULD be distributable using OCI-compatible registries.

Recommended media types:

Component	Media type
Manifest	`application/vnd.oci.image.manifest.v1+json` or OCI artifact equivalent
Agent config	`application/vnd.agentrc.agent.config.v1+json`
Agentfile	`application/vnd.agentrc.agent.agentfile.v1+text`
Lockfile	`application/vnd.agentrc.agent.lock.v1+json`
Cedar policy	`application/vnd.agentrc.agent.policy.cedar.v1+text`
Source layer	`application/vnd.agentrc.agent.source.layer.v1.tar+gzip`
Tool layer	`application/vnd.agentrc.agent.tool.layer.v1.tar+gzip`
Skill layer	`application/vnd.agentrc.agent.skill.layer.v1.tar+gzip`

Recommended annotations:

io.agentrc.agentfile.version
io.agentrc.agent.name
io.agentrc.policy.hash
io.agentrc.base.digest
io.agentrc.risk.tier
org.opencontainers.image.title
org.opencontainers.image.version
org.opencontainers.image.source
org.opencontainers.image.revision
org.opencontainers.image.created

Implementations SHOULD support signing and provenance metadata.

15. Registry model

A registry MAY host:

complete agent packages;
base agent packages;
skills;
tools;
toolsets;
policy bundles;
verified enterprise templates;
metadata/risk reports.

Registry clients SHOULD support:

pull by digest;
signature verification;
provenance inspection;
policy inspection before execution;
risk-tier display;
dependency graph display;
offline/cache mode.

agentrc does not require a central registry. Public community registries, private enterprise registries, and air-gapped registries should all be possible.

16. Inheritance and monotonic security

If FROM references another agentrc package, the child inherits the parent package’s declared capabilities and restrictions.

A child package MAY:

add implementation detail;
add skills;
add tools allowed by the parent ceiling;
narrow network access;
narrow filesystem access;
add stricter policy;
increase audit requirements.

A child package MUST NOT:

remove inherited denies;
widen network access beyond the parent ceiling;
widen filesystem access beyond the parent ceiling;
expose credentials outside the parent ceiling;
disable inherited audit requirements;
increase delegation authority beyond the parent ceiling;
weaken inherited rate limits unless an explicit parent rule permits it.

This allows a security team to publish hardened base packages that downstream teams can reuse safely.

17. Tool projection profile

The core Agentfile does not require a single tool implementation model.

A tool MAY be implemented as:

a local executable;
a framework function;
an MCP tool;
a remote API adapter;
a runner-native capability.

The optional Tool Projection Profile defines a command-oriented surface so tools can be discovered, inspected, and invoked without a provider-specific SDK.

Recommended projection:

/agentrc/tools/<tool-name>
/agentrc/tools/<tool-name>.schema.json
/agentrc/tools/<tool-name>.help
/agentrc/tools/<tool-name>.events
/agentrc/functions/<function-name>
/agentrc/skills/<skill-name>/SKILL.md
/agentrc/proc/audit
/agentrc/proc/policy
/agentrc/proc/limits

This profile is optional. It should not be used to imply agentrc is a runtime. It is a portability profile that runners may implement.

18. Runner conformance profile

A runner may claim conformance to one or more profiles.

A runner claiming the Core Runner Profile MUST:

read the package metadata;
identify supported and unsupported directives;
reject unknown required directives;
execute the declared CMD or fail with an unsupported-entrypoint error;
enforce declared security boundaries it claims to support;
fail closed when it cannot enforce a required boundary;
produce audit events if required by AUDIT;
never leak credential values in logs or audit;
report the effective execution profile.

A runner MAY be implemented using local processes, containers, gVisor, microVMs, cloud jobs, Kubernetes, SSH, serverless workers, or managed agent runtimes. The implementation substrate is not specified by agentrc.

19. Multi-agent workflows

The Agentfile defines one agent.

Multi-agent workflows should be defined in a companion specification, not inside Agentfile.

A future workflow specification SHOULD reference packaged agents by OCI reference or digest and MAY use state-machine concepts such as:

Task;
Choice;
Parallel;
Map;
Wait;
Retry;
Catch;
Timeout.

See profiles/AGENT_WORKFLOW_DRAFT.md for a non-normative YAML example.

20. Conformance summary

This draft defines these profiles:

Profile	Purpose
Core Agentfile Profile	Parse and validate the Agentfile grammar
Security Declaration Profile	Interpret boundary declarations and fail closed
Cedar Policy Profile	Evaluate Cedar authorization requests
OCI Package Profile	Build, inspect, push, pull, and verify packages
Tool Projection Profile	Expose command-oriented tool/function discovery and invocation
Runner Conformance Profile	Execute packages while honoring declared boundaries
Workflow Draft Profile	Non-normative future multi-agent orchestration

An implementation should state exactly which profiles it supports.

21. Security considerations

Agent packages may request dangerous capabilities. Declarative does not mean safe.

Reviewers and registries should surface:

requested network destinations;
requested mounts and mutability;
requested credentials;
high-risk tools such as shell, browser, computer-use, code execution, dynamic tool loading, and broad MCP access;
policy denies and permits;
inherited restrictions;
package signatures;
provenance;
vulnerability scan results;
unsupported runner controls.

A runner MUST NOT silently ignore security controls that the package marks as required.

22. Versioning

The specification uses semantic versions:

MAJOR.MINOR.PATCH[-PRERELEASE]

Agentfiles SHOULD declare the syntax version using a parser-compatible comment:

# syntax=agentrc.agentfile/v0.1

Packages SHOULD include the Agentfile version as package metadata and OCI annotation.

23. Compatibility with existing work

This draft is aligned with the current agentrc repository structure:

packages/aio-core contains Agentfile parsing, types, audit, and Cedar scaffolding.
packages/aio-buildtime contains compile, lock, schema, OCI, and registry package work.
packages/aio-runtime contains candidate runner/driver code and enforcement experiments.
packages/aio contains the CLI.
examples/ contains current Agentfile examples.

This draft intentionally frames runtime code as implementation and test harness, not as the definition of agentrc itself.

24. Open questions

Should ISOLATION, IMAGE, SLICE, PLUGIN, and BACKEND remain in Agentfile or move to a separate run manifest?
Should BIND require a mode in v0.1, or should two-argument compatibility be normative?
Should Cedar be mandatory for security-conformant runners or only the default policy profile?
Should ALLOW/DENY shorthand remain long-term or compile immediately into Cedar?
Should tool projection be required for all runners or only for developer/local profiles?
Should an agentrc package be modeled as an OCI image, OCI artifact, or both?
What minimal metadata should be required before publishing a package to a public registry?
How should multi-agent workflow policy ceilings compose across package boundaries?
Should MODEL be a directive, or should model selection remain inside CMD/runner configuration?
What should the first public conformance test suite include?

25. Summary

agentrc is the Agentfile and agent-package specification.

The Agentfile declares one agent. The lockfile pins its resolved dependencies. The package makes it portable. The policy makes its boundaries reviewable. The registry makes it shareable. Compatible runners execute it. agentrc itself remains the neutral declaration, packaging, and governance layer.

agentrc Specification

1. Status of this document

2. Abstract

3. Design goals

4. Non-goals

5. Core terminology

5.1 Agent

5.2 Agentfile

5.3 Agent package

5.4 Runner

5.5 Capability

5.6 Boundary

5.7 Policy

5.8 Registry

5.9 Profile

6. Layering model

7. Agentfile syntax model

8. Minimal valid Agentfile

9. Agentfile directives

9.1 AGENT

9.2 FROM

9.3 SHELL

9.4 CMD

9.5 TOOL

9.6 TOOLSET

9.7 FUNCTION

9.8 SKILL

9.9 SERVER

9.10 MCP

9.11 URL

9.12 CRED

9.13 BIND

9.14 MOUNT

9.15 PLUGIN

9.16 POLICY block

9.17 ALLOW, DENY, and RATELIMIT

9.18 AUDIT

9.19 TIMEOUT

9.20 LIMIT

9.21 SLICE

9.22 IMAGE

9.23 ISOLATION

9.24 BROKER

9.25 BACKEND

9.26 TRACE

9.27 MEMORY

9.28 OPTIMIZER

9.29 HEALTHCHECK

9.30 SOP