Manifest reference

agentserve.app.yaml sits at the root of your app. It says what the app is called, which pages it shows, what it may reach, what to create when it is installed, and how much it may spend each month. The platform validates it on every upload, and the install screen lists its permissions for the admin.

A complete example

# yaml-language-server: $schema=https://agentserve.valnoraelric.com/schemas/agentserve.app.schema.json
name: field-visit-logger
version: 0.1.0
title: Field visit logger
icon: ./dist/icon.svg
pages:
  - id: visits
    title: Visits
    entry: ./dist/index.html#/visits
  - id: new-visit
    title: New visit
    entry: ./dist/index.html#/new
permissions:
  tables: [visits]
  files: write
  relays: [Field follow-up]
requires:
  tables: ./tables/*.yaml
  relays: ./relays/*.yaml
budget:
  monthlyUsd: 25

The first line points editors that use the YAML language server (for example VS Code with the YAML extension) at the published JSON Schema, so you get completion and errors as you type. Every template already has it.

Fields

The table below is generated from the manifest's JSON Schema, so it always matches what the platform accepts. A field marked Required inside an optional object (such as budget.monthlyUsd) is required only when that object is present. A manifest with any field not listed here is refused.

Paths and globs

Every path in the manifest is relative to the manifest, such as ./dist/index.html or ./tables/*.yaml. A path may not start with /, may not be a URL, and may not leave the bundle with ...

Globs match files in the bundle: * matches within one folder, ** matches any number of folders, and ? matches one character. Fields that take a glob also take a list of globs.

When you upload, the platform checks that:

• every page entry, panel entry and Chat card entry is an HTML file in the bundle,
• the icon, when set, is in the bundle,
• requires.tables, when set, matches at least one file.

Pages

Each page is one entry in the Apps section's navigation. Most apps are a single-page application with one index.html and a route per page, written as a fragment: ./dist/index.html#/visits. The app reads the fragment to decide what to show. You can have up to 20 pages, and their ids must be unique.

Permissions

permissions names what the app may reach. The app always acts as the person using it, so a permission never gives anyone more access than they already have. It only narrows. See Security model.

permissions:
  ai:
    models: [gpt-5.5]
    media: [image]
  knowledge: [Product docs]
  integrations: [slack_send_message]
  chat: answer

Model, media and Chat calls run on the workspace's own provider key when it has one, and on Agent Serve's hosted key otherwise. Either way the person's permission group decides which providers and models they may use, so an app cannot reach a model the person could not. The app never sees a credential: integration actions use the person's connected account on the server, and the frame only gets the result.

Names are matched against the workspace the app is installed in, when each call is made:

• A name with no match grants nothing. Calls naming it fail with not_found.
• If several workflows share a name, the app cannot run any of them until one is renamed.
• A call that names a resource the manifest does not list fails with forbidden, even if the person could reach it.

Slots

A name under permissions must match a resource in every workspace the app is installed in. When workspaces call the same thing by different names — a pipeline table, a docs knowledge base — declare a slot instead. The admin picks the workspace's own resource for each slot on the install review, and can change it later on the Manage page. The app calls methods with the slot's name.

slots:
  pipeline:
    kind: table
    title: Pipeline table
    description: Accounts and their open deals come from this table.
    default: pipeline_opportunities
  docs:
    kind: knowledge_base
    title: Knowledge base
    description: Questions are answered from this one.
    required: false

• A slot is a permission by itself. A table slot lets the app reach the one table the admin bound to it, exactly as listing that table under permissions.tables would, and every call is still held to the person's own access.
• Call methods with the slot name: tables.query({ table: 'pipeline' }), knowledge.search({ knowledgeBases: ['docs'] }), workflows.run('intake'), relays.assignTask({ relay: 'reviewers' }).
• A model slot names a chat model the admin picks; pass the slot name as model in ai.complete. The workspace's semantic model is not a slot: there is one per workspace, reached with permissions.model: read.
• A slot whose resource is deleted or archived falls back to its default, else it is unbound. Calls to an unbound slot fail with not_found and say an admin picks it on the Manage page, where it shows as Needs setup.
• tables.list marks a table bound to a slot with that slot's name, and viewer.get lists each slot and whether it is set up.
• A slot's name must not also appear under permissions for the same kind.
• Triggers, actions and background scopes may name a slot wherever they name a table, workflow, Relay or knowledge base.

Literal names keep working: a name under permissions is a fixed slot whose only binding is that name.

Requires: tables, rules and Relays

requires lists definitions the install creates when the workspace does not already have one with the same name. Existing ones are left as they are. The install is safe to retry: anything it already created is skipped.

Tables

One YAML file per table:

name: visits
description: Customer visits logged in the field
columns:
  - { name: customer, type: string, required: true }
  - { name: visited_on, type: date, required: true }
  - { name: outcome, type: string }
  - { name: deal_value, type: currency }
  - { name: follow_up, type: boolean }

A table that cannot be created fails the whole install, with the file and field in the error. The installing admin's own plan limits apply.

Rules

One YAML or JSON file per rule. The file is a rule definition exactly as the Rules API takes it, with a non-empty name; the rule service validates it in full when the install creates it.

Rules need model management. If the installing admin's permission group does not include it, or a definition is invalid, the install still succeeds and reports the rule as skipped with the reason, so someone can create it in Rules.

Relays

One YAML or JSON file per Relay. The install creates the Relay, sets it up from the file, and publishes it when the definition is complete and the admin leaves Publish now on:

# yaml-language-server: $schema=https://agentserve.valnoraelric.com/schemas/agentserve.relay.schema.json
name: Legal review
description: Reviews contracts flagged by Contract triage
specialization: legal
instructions: |
  You review contracts that Contract triage flagged against the team's playbook.
  For every flagged clause, accept, counter with exact wording, or escalate.
delivers:
  summary: A decision for every flagged clause, with the reason and any counter wording.
  as: task_result
escalation: Escalate anything that touches liability caps, indemnities or personal data.
autonomy: assist
approvals: { approvers: installer, expireAfterHours: 48 }
tools: [workspace_read, tables, knowledge]
workflows:
  - workflow: Send redlines
responsibilities:
  - name: Weekly review backlog
    objective: List contracts that have waited more than five working days.
    schedule: { cron: '0 9 * * 1', timezone: UTC }

The editor schema is published as agentserve.relay.schema.json.

A definition is complete when it has instructions and delivers. The install review shows each Relay with its instructions and a Publish now switch, on by default for a complete definition when the admin may publish Relays. Everything happens as the installing admin, through the same steps as the Relays page: the Relay is created, its setup saved, its routines added and, when chosen, published, with the same setup and go-live checks. When a step cannot finish (a workflow the workspace does not have, a check that fails, a permission group without Relays), the Relay stays a draft and the review lists exactly what is missing, with a link to finish its setup.

Panels and Chat cards

An app can provide small views that render outside its own pages, in the same sandboxed frame:

• panels — dashboard panels people add to a dashboard.
• chatBlocks — cards Chat can show in a reply.

Declare them as a list with an id, title and entry each, or as a glob of HTML files:

panels:
  - id: pipeline
    title: Pipeline
    entry: ./dist/panels/pipeline.html
chatBlocks: ./dist/cards/*.html

With a glob, each matching HTML file becomes one component whose id and title come from its file name, lowercased, with other characters turned into -. A file whose name does not make a valid id is left out, and at most 50 are used. A panel or card can call resize from the SDK to fit its height to its content.

Tools

tools names your code tools, such as ./tools/*: each <name>.tool.yaml and its <name>.ts, .mts, .js, .mjs or .py source. They are uploaded with the version, checked on upload, stored with it, and run on Agent Serve for the app, Chat, Relays and workflows. They are never served to the app's frame. See Code tools.

Plugin sections

An app becomes a plugin when it also adds things to the workspace's own surfaces. Each section is optional:

• triggers run a handler on a schedule or when something happens in the workspace, in the background.
• commands add slash commands to Chat.
• actions add menu items to files, table rows, workbook queries and dashboard panels.
• settings is a form an admin fills in for the install.
• connectors bring MCP servers (tools from other services) the plugin calls.
• skills add instruction packs to the workspace's skill library.
• background limits background runs; listing is what the plugin catalog shows.

A handler is one of the app's own code tools, named by its tool name; an upload is refused when a handler names a tool the version does not ship. Every resource a trigger or action names must also be in permissions. See Plugins for each section, the handler input and output, and how background runs are authorized.

Build

build tells a Git deploy how to build the app: the command to run and which paths make up the bundle. agentserve app deploy builds on your machine and ignores it.

Budget

budget.monthlyUsd caps what the app's paid work may spend in a calendar month, measured in UTC. Paid work is the workflow runs, Relay tasks and code tool runs the app starts, its model completions, generated media, Chat answers and knowledge searches, and the hosted-key cost of its integration actions. Once the month's spend reaches the cap, those calls fail with budget_exhausted until the next month.

An admin can set a different budget for an install on its Manage page, which takes precedence over the manifest. With no budget in either place, the app's spend is not capped. See Budgets.