AgentFile Layer

AgentFile Layers let you override agent configuration on a per-Pod basis without modifying the base AgentFile.

What is AgentFile Layer?

An AgentFile Layer is a user-provided override that is merged on top of the base AgentFile at Pod creation time. AgentsMesh uses a 3-tier merge model: the base AgentFile (agent defaults) is merged with user preferences (saved settings), then the Layer (per-Pod runtime overrides) is applied last. The Layer takes highest priority.

Base AgentFile  →  User Preferences  →  Layer (per-Pod override)
 (agent default)    (saved settings)     (runtime customization)

Supported Declarations

Only a subset of AgentFile declarations can be used in a Layer. These are the declarations that make sense to override at runtime:

MODE

CREDENTIAL

PROMPT

PROMPT_POSITION

CONFIG

REPO

BRANCH

GIT_CREDENTIAL

API Usage

When creating a Pod via the REST API, pass the Layer as the agentfile_layer field in the request body. The Layer is a string containing AgentFile syntax:

POST /api/v1/pods
{
  "agent_slug": "claude-code",
  "runner_id": "runner-abc",
  "agentfile_layer": "CONFIG model = \"opus\"\nPROMPT \"Fix the login bug\""
}

Frontend Editor

In the Pod creation form, toggle Source Mode to edit the AgentFile Layer directly using the built-in CodeMirror editor with syntax highlighting and auto-completion. Form fields (model, prompt, repository, etc.) are automatically synced with the Layer content.

Common Examples

Here are common Layer patterns for customizing Pod behavior:

Override the model

CONFIG model = "opus"

Set permission mode

CONFIG permission_mode = "bypassPermissions"

Add an initial prompt

PROMPT "Fix the login bug in auth.ts"

Select a repository and branch

REPO "my-org/my-repo"
BRANCH "feature/xyz"

Switch to ACP mode

MODE acp