Define your manifest (agentapp.json)

The manifest is the agentapp.json file at the root of your project. It describes your app to the platform.

Required fields

Field	Description
`id`	Canonical app ID, format `app.<service>` (e.g. `app.google.gmail`)
`version`	Semantic version (e.g. `1.0.0`)
`name`	Display name (max 50 chars)
`description`	Full description (10–500 chars)
`tagline`	One-line summary for catalog cards (5–120 chars)
`author`	Object with `name`, `email`, and optional `url`
`logo`	Path or URL to the app's branded logo (SVG recommended; PNG ≥ 1024×1024)
`logoMono`	Monochrome SVG version of the logo (host recolors freely)
`terms`	Terms of service URL
`category`	App category (e.g. `productivity`, `developer`, `communication`)
`entrypoint`	Object with `type` (`module` or `commonjs`), `path`, and optional `export` (default `default`)
`runtime`	Runtime configuration — discriminated by `transport`: `stdio`, `http`, or `websocket`

Capabilities

Capabilities are boolean flags that advertise which protocol-level features your app uses. All default to a sensible value if omitted.

Capability	Default	Description
`tools`	`true`	Exposes callable tools via the session plane
`events`	`false`	Emits and/or receives events
`health`	`true`	Responds to `health_check` requests
`streaming`	`false`	Supports progress, stream, and log messages

{
  "capabilities": {
    "tools": true,
    "events": false,
    "health": true,
    "streaming": true
  }
}

Runtime

The runtime field is discriminated by transport. Three transports are supported:

stdio

The host spawns a child process and communicates over stdin/stdout.

{
  "runtime": {
    "transport": "stdio",
    "command": "node",
    "args": ["./dist/index.js"],
    "cwd": ".",
    "env": {}
  }
}

Field	Required	Description
`transport`	yes	Must be `"stdio"`
`command`	yes	Command to execute
`args`	no	Arguments for the command
`cwd`	no	Working directory relative to the manifest
`env`	no	Additional environment variables

http

The app runs as an HTTP server. Either url or a teros extension must be present.

{
  "runtime": {
    "transport": "http",
    "url": "https://my-app.example.com",
    "healthCheck": "/health"
  }
}

When the Teros station manages the app lifecycle, use the teros extension instead of url:

{
  "runtime": {
    "transport": "http",
    "teros": {
      "containerMode": "docker",
      "dockerImage": "my-app:latest",
      "mountVolume": true
    }
  }
}

websocket

The app connects to a WebSocket endpoint.

{
  "runtime": {
    "transport": "websocket",
    "url": "wss://my-app.example.com/ws",
    "healthCheck": "/health"
  }
}

Teros runtime extension (`runtime.teros`)

When using the http transport with the Teros station, the teros object configures how the station deploys and manages your app container.

Field	Default	Description
`containerMode`	`"process"`	Container execution mode: `process` (native), `docker` (shared container), or `per-app` (isolated container)
`dockerImage`	—	Custom Docker image. Required when `containerMode` is `docker` or `per-app`
`appDataMount`	`false`	Mount a persistent directory into the container at `/app-data`
`mountVolume`	`false`	Mount the workspace volume directly at `/workspace` (see below)
`systemEnvironment`	—	Additional environment variables injected at container launch
`systemVolumes`	—	System-level volume mounts (`hostPath`, `containerPath`, `readOnly`)
`allowSecretsInEnvironment`	`false`	Allow secret-looking names in `systemEnvironment` (use `auth.systemSecrets` instead)

mountVolume

mountVolume is a boolean flag (default false) that controls whether the station bind-mounts the workspace's volume directory directly into the container at /workspace.

When true, your app can use Node's fs module (or any POSIX file API) to read and write files in the workspace natively — no SDK callbacks required.

When false (the default), your app accesses workspace files through ctx.volume SDK callbacks. This is the right choice for most apps.

Use mountVolume: true only when your app needs real POSIX filesystem access — for example:

A Bash app that runs shell commands expecting a real filesystem
A Filesystem app that uses fs.readFile / fs.writeFile directly

Most apps (Gmail, Calendar, Slack, etc.) should leave it at false and use ctx.volume callbacks.

{
  "runtime": {
    "transport": "http",
    "teros": {
      "containerMode": "docker",
      "dockerImage": "my-filesystem-app:latest",
      "mountVolume": true
    }
  }
}

Logo policy

Never generate logos with AI. Source from official brand resources.

Next steps

Implement tools — add tools with the SDK
Test your app — run the conformance suite
Validate & package — validate and pack your app

Define the manifest