.Worker v1

The .Worker viewer

A .Worker file defines an agentic worker: its job, the accounts it acts through, what it may do, what starts it, and where it runs. Paste one here to color it, format it and check it against the spec. New to the format? Read the documentation.

weekly-pipeline.Worker

Valid

apiVersion: agenticworkers.com/v1
kind: Worker
id: weekly-pipeline                    # immutable; becomes the slug and home directory
name: Weekly Pipeline Summary          # display name; safe to change
version: 2.1.0                         # new: semver of this definition
from: agenticworkers/super-agent:1     # base worker from the registry
 
job:
  summary: Each Monday, summarize last week's closed deals for the sales lead.
  done_when: A summary matching the output schema is posted to team chat.
  stop_and_ask:                        # instructions to the model, not enforcement
    - a deal is missing an amount
 
interface:                             # new
  output: { schema: ./schemas/summary.json }
  artifacts: [text/markdown]           # saved to workspace/artifacts/
 
model:
  id: auto                             # Agent.model
  reasoning: medium                    # new
  fallback: [minimax/minimax-m3]       # new
 
instructions:
  soul: ./SOUL.md                      # Agent.instructions, max 50,000 characters
  memory: { enabled: true }
 
skills:
  - agenticworkers/crm-weekly-summary@2    # SkillRegistry key and version
 
connections:                           # see Connections
  - { id: crm, provider: hubspot, via: composio, auth: oauth, required: true,
      tools: { allow: [HUBSPOT_LIST_DEALS, HUBSPOT_GET_DEAL, HUBSPOT_UPDATE_DEAL] } }
  - { id: team-chat, provider: slack, via: composio, auth: oauth, required: true,
      tools: { allow: [SLACK_SEND_MESSAGE] } }
 
policy:                                # new: replaces approvals.mode for this worker
  default: deny
  rules:
    - allow: [crm.HUBSPOT_LIST_DEALS, crm.HUBSPOT_GET_DEAL]
    - require_approval: [crm.HUBSPOT_UPDATE_DEAL]
    - allow: [team-chat.SLACK_SEND_MESSAGE]
  unattended: same                     # today scheduled runs auto-approve everything
 
triggers:
  - id: monday-summary                 # stable key; apply stores id -> Hermes routine id
    cron: "0 8 * * 1"
    run: { skill: crm-weekly-summary }
    deliver: chat                      # chat | telegram | chat_and_telegram | none
  - id: deal-won                       # new for hosted agents
    event: { connection: crm, type: HUBSPOT_DEAL_STAGE_CHANGED, filter: { stage: closedwon } }
    run: { prompt: Add this deal to the current summary draft. }
 
evals:                                 # new
  suite: ./evals/weekly.yaml
  gate: { pass_rate: 0.9 }             # push and apply refuse a version below this
 
data:                                  # new
  retention: { sessions: 90d, uploads: 30d }
  redact: [email, phone]
 
network:                               # new
  egress: limited
  allow: [api.hubapi.com, slack.com]
 
expose:                                # new
  a2a: { card: auto, sign: true }
 
resources:
  memory: 2Gi                          # request; the box sizes itself from the sum
  limits: { memory: 3Gi }              # new: per-worker cgroup
 
---
apiVersion: agenticworkers.com/v1
kind: Assignment
id: weekly-pipeline-acme
worker: agenticworkers/weekly-pipeline:2.1.0
team: acme-client                      # Organization (Team workspace); required for hosted
box: provider-us-east
 
identity:
  sponsor: ops@acme.com                # accountable person; receives approvals and alerts
  billing: provider                    # provider | client -> billingOwnerUserId
 
bind:
  crm: { owner: client, invite: { email: ops@acme.com, expires: 7d } }
  team-chat: { owner: client, invite: { email: ops@acme.com, expires: 7d } }
 
secrets:
  HUBSPOT_PORTAL_ID: vault://box/ACME_HUBSPOT_PORTAL_ID   # env name -> vault name: new
 
overrides:
  instructions.bootstrap: ./acme/company-brain.md         # Agent.companyBrainBootstrap
 
budget: { usd_per_day: 15, on_exceed: pause }             # new
 
storage:
  backups: { cadence: daily, hour_utc: 3, keep: { count: 7, days: 30 } }   # BackupSubscription, per agent
 
---
apiVersion: agenticworkers.com/v1
kind: Box
id: provider-us-east
team: northwind-ai                     # the provider's org
image: agw/hermes:fcd5e2c              # update_runtime when this changes
region: iad
machine: { cpus: 4, memory: 8Gi }      # pinned; resize_box
volume: { size: 40Gi }                 # grows only; extend_volume restarts the machine
availability: always-on                # always-on | idle
sleep:                                 # OrgBox.sleepSchedule
  timezone: America/New_York
  windows: [{ from: sat 00:00, to: sun 23:59 }]
telemetry:                             # new
  otlp: https://otel.northwind.ai
assignments:
  - ./acme.Worker
  - ./globex.Worker

apiVersion: agenticworkers.com/v1
kind: Worker
id: weekly-pipeline                    # immutable; becomes the slug and home directory
name: Weekly Pipeline Summary          # display name; safe to change
version: 2.1.0                         # new: semver of this definition
from: agenticworkers/super-agent:1     # base worker from the registry

job:
  summary: Each Monday, summarize last week's closed deals for the sales lead.
  done_when: A summary matching the output schema is posted to team chat.
  stop_and_ask:                        # instructions to the model, not enforcement
    - a deal is missing an amount

interface:                             # new
  output: { schema: ./schemas/summary.json }
  artifacts: [text/markdown]           # saved to workspace/artifacts/

model:
  id: auto                             # Agent.model
  reasoning: medium                    # new
  fallback: [minimax/minimax-m3]       # new

instructions:
  soul: ./SOUL.md                      # Agent.instructions, max 50,000 characters
  memory: { enabled: true }

skills:
  - agenticworkers/crm-weekly-summary@2    # SkillRegistry key and version

connections:                           # see Connections
  - { id: crm, provider: hubspot, via: composio, auth: oauth, required: true,
      tools: { allow: [HUBSPOT_LIST_DEALS, HUBSPOT_GET_DEAL, HUBSPOT_UPDATE_DEAL] } }
  - { id: team-chat, provider: slack, via: composio, auth: oauth, required: true,
      tools: { allow: [SLACK_SEND_MESSAGE] } }

policy:                                # new: replaces approvals.mode for this worker
  default: deny
  rules:
    - allow: [crm.HUBSPOT_LIST_DEALS, crm.HUBSPOT_GET_DEAL]
    - require_approval: [crm.HUBSPOT_UPDATE_DEAL]
    - allow: [team-chat.SLACK_SEND_MESSAGE]
  unattended: same                     # today scheduled runs auto-approve everything

triggers:
  - id: monday-summary                 # stable key; apply stores id -> Hermes routine id
    cron: "0 8 * * 1"
    run: { skill: crm-weekly-summary }
    deliver: chat                      # chat | telegram | chat_and_telegram | none
  - id: deal-won                       # new for hosted agents
    event: { connection: crm, type: HUBSPOT_DEAL_STAGE_CHANGED, filter: { stage: closedwon } }
    run: { prompt: Add this deal to the current summary draft. }

evals:                                 # new
  suite: ./evals/weekly.yaml
  gate: { pass_rate: 0.9 }             # push and apply refuse a version below this

data:                                  # new
  retention: { sessions: 90d, uploads: 30d }
  redact: [email, phone]

network:                               # new
  egress: limited
  allow: [api.hubapi.com, slack.com]

expose:                                # new
  a2a: { card: auto, sign: true }

resources:
  memory: 2Gi                          # request; the box sizes itself from the sum
  limits: { memory: 3Gi }              # new: per-worker cgroup

---
apiVersion: agenticworkers.com/v1
kind: Assignment
id: weekly-pipeline-acme
worker: agenticworkers/weekly-pipeline:2.1.0
team: acme-client                      # Organization (Team workspace); required for hosted
box: provider-us-east

identity:
  sponsor: ops@acme.com                # accountable person; receives approvals and alerts
  billing: provider                    # provider | client -> billingOwnerUserId

bind:
  crm: { owner: client, invite: { email: ops@acme.com, expires: 7d } }
  team-chat: { owner: client, invite: { email: ops@acme.com, expires: 7d } }

secrets:
  HUBSPOT_PORTAL_ID: vault://box/ACME_HUBSPOT_PORTAL_ID   # env name -> vault name: new

overrides:
  instructions.bootstrap: ./acme/company-brain.md         # Agent.companyBrainBootstrap

budget: { usd_per_day: 15, on_exceed: pause }             # new

storage:
  backups: { cadence: daily, hour_utc: 3, keep: { count: 7, days: 30 } }   # BackupSubscription, per agent

---
apiVersion: agenticworkers.com/v1
kind: Box
id: provider-us-east
team: northwind-ai                     # the provider's org
image: agw/hermes:fcd5e2c              # update_runtime when this changes
region: iad
machine: { cpus: 4, memory: 8Gi }      # pinned; resize_box
volume: { size: 40Gi }                 # grows only; extend_volume restarts the machine
availability: always-on                # always-on | idle
sleep:                                 # OrgBox.sleepSchedule
  timezone: America/New_York
  windows: [{ from: sat 00:00, to: sun 23:59 }]
telemetry:                             # new
  otlp: https://otel.northwind.ai
assignments:
  - ./acme.Worker
  - ./globex.Worker

3 documents · Worker, Assignment, BoxLn 1, Col 1 · .Worker v1

No problems

This file follows the .Worker v1 rules.

Everything runs in your browser. Nothing you paste is uploaded. Press Cmd+S to format, Tab to indent, and Esc then Tab to leave the editor.

Three kinds in one file

A .Worker file holds one or more YAML documents separated by ---. Each one declares a kind.

kind: Worker

The portable definition: job, model, instructions, skills, the connections it needs, policy and triggers.

kind: Assignment

One deployment of a worker for one client: whose accounts fill each connection, who approves, and the budget.

kind: Box

The machine: image, region, size, volume, sleep schedule, and the assignments that run on it.

Lint rules

Every check the viewer runs. Rule ids are stable, so you can refer to them in reviews.

.Worker lint rules with severity and description
Rule	Severity	What it checks
yaml/syntax	error	The file must be valid YAML.
doc/api-version	error	Every document declares apiVersion: agenticworkers.com/v1.
doc/kind	error	kind is Worker, Assignment or Box.
doc/id	error	id is required, lowercase, and unique in the file. It never changes when the name does.
doc/unknown-key	warning	Top-level keys must be known for the kind. Close misspellings get a suggestion.
job/summary	warning	A Worker states its job in one sentence.
model/provider	warning	openai-codex and custom providers are applied as box config, not stored by the platform yet.
connection/shape	error	Each connection has an id, a via of composio, mcp or env, and the fields that via needs.
connection/allow-list	error	An MCP connection lists the tools it may use. An empty list would expose every tool.
connection/enum	error	auth, on_missing and on_expired use the documented values.
policy/rule	error	policy.default is allow or deny, and each rule is allow, require_approval, forbid or require.
policy/unknown-connection	warning	A dotted tool reference starts with a declared connection id.
trigger/shape	error	Each trigger has an id and exactly one of cron, every, event or webhook.
trigger/cron	error	cron has five fields; every is a number and a unit (5m, 1h).
trigger/deliver	warning	deliver is chat, telegram, chat_and_telegram or none.
trigger/event-connection	error	An event trigger names a declared connection.
secret/inline	error	Secret values never appear in the file. Use vault://box/NAME.
secret/name	error	Secret names are uppercase and avoid reserved prefixes (AGW_, HERMES_, COMPOSIO, GATEWAY_, API_SERVER_, BOX_GATEWAY).
secret/agent-scope	warning	vault://agent/ references are not supported by the platform yet.
bind/unknown-connection	error	An Assignment binds only connections its Worker declares.
bind/missing	error	An Assignment binds every required connection.
bind/mixed-owners	error	Composio connections on one worker share one owner: org, or agent and client. The platform uses one Composio account set per agent.
bind/invite	error	Client invites need owner client or agent, and expire in 1d, 7d or 30d.
box/machine	error	Box cpus are 1, 2, 4, 6 or 8, memory is at most 16Gi, and volumes are at most 100Gi.
box/capacity	warning	Worker memory requests on a box fit inside its machine memory.
resources/limits	error	A memory limit is at least the memory request.
value/todo	warning	TODO values must be filled in before apply.