.takos/app.yml

Status

このページは current contract です。Takos は single-document YAML の kind: App manifest を正本として解釈します。

Takos の app deploy は、リポジトリ内の .takos/app.yml を読んで行います。現在の parser は multi-document の Package / Workload / Binding 形式を受け付けません。

最小構成

apiVersion: takos.dev/v1alpha1
kind: App
metadata:
  name: notes-assistant
spec:
  version: 0.3.0
  services:
    web:
      type: worker
      build:
        fromWorkflow:
          path: .takos/workflows/deploy.yml
          job: bundle
          artifact: web
          artifactPath: dist/worker

有効な例全体は current example を参照してください。

トップレベル

field	required	description
apiVersion	yes	現在は takos.dev/v1alpha1 固定
kind	yes	App 固定
metadata.name	yes	app 名
metadata.appId	no	既存 app へ再デプロイする場合の固定 ID
spec.version	yes	表示用 version
spec.description	no	説明
spec.icon	no	icon URL または path
spec.category	no	app, service, library, template, social
spec.tags	no	タグ配列
spec.capabilities	no	platform capability 名の宣言
spec.env.required	no	deploy 時に満たすべき env 名
spec.oauth	no	OAuth client 自動登録設定
spec.takos.scopes	no	Takos-managed token の scope
spec.resources	no	app が要求する resource map
spec.services	yes	deploy 対象 service map
spec.routes	no	route 配列
spec.mcpServers	no	MCP server 公開設定
spec.fileHandlers	no	storage/file handler 登録

metadata

metadata:
  name: notes-assistant
  appId: app_1234567890

• metadata.name は必須です。
• metadata.appId は control plane 側の既存 app identity を pin したいときだけ使います。

spec.services

現在の public manifest で使える service type は worker のみです。

spec:
  services:
    web:
      type: worker
      build:
        fromWorkflow:
          path: .takos/workflows/deploy.yml
          job: bundle
          artifact: web
          artifactPath: dist/worker
      env:
        PUBLIC_APP_NAME: Notes Assistant
      bindings:
        d1: [primary-db]
        r2: [assets]
        kv: [cache]
        vectorize: [embeddings]
        queues: [reminders]
        analytics: [events]
        workflows: [digest-workflow]
        durableObjects: [session-do]
        services: [web]
      triggers:
        schedules:
          - cron: "*/15 * * * *"
            export: scheduled
        queues:
          - queue: reminders
            export: queue

build contract

spec.services.<name>.build.fromWorkflow は必須です。

field	required	description
path	yes	.takos/workflows/ 配下の workflow path
job	yes	deploy artifact を出す job 名
artifact	yes	workflow artifact 名
artifactPath	yes	artifact 内の worker bundle path

現在は次を 受け付けません。

• build.command
• build.output
• build.cwd
• entry
• local build shell を直接書く形式

bindings

binding list は resource 名を参照します。型が一致しない場合は validation error になります。

triggers

• triggers.schedules[].cron
• triggers.schedules[].export
• triggers.queues[].queue
• triggers.queues[].export

queue trigger の queue は spec.resources 内の type: queue resource を参照する必要があります。

spec.resources

resource は map です。key が resource 名になります。

spec:
  resources:
    primary-db:
      type: d1
      binding: DB
      migrations:
        up: .takos/migrations/primary-db/up
        down: .takos/migrations/primary-db/down
    assets:
      type: r2
      binding: ASSETS

サポートされる resource type

type	fields
d1	binding, migrations
r2	binding
kv	binding
secretRef	binding
vectorize	binding, vectorize.dimensions, vectorize.metric
queue	binding, queue.maxRetries, queue.deadLetterQueue, queue.deliveryDelaySeconds
analyticsEngine	binding, analyticsEngine.dataset
workflow	binding, workflow.service, workflow.export, workflow.timeoutMs, workflow.maxRetries
durableObject	binding, durableObject.className, durableObject.scriptName

追加ルール

• queue.deadLetterQueue は別の type: queue resource を参照する必要があります。
• workflow.service は既存 service 名を参照する必要があります。
• migrations は文字列または { up, down } のどちらでも指定できます。

spec.routes

spec:
  routes:
    - name: app
      service: web
      path: /
      timeoutMs: 30000

field	required	description
service	yes	route の target service
name	no	route 表示名
path	no	公開 path
ingress	no	ingress service 名
timeoutMs	no	route timeout

• service は既存 service を参照する必要があります。
• ingress を使う場合も worker service を参照する必要があります。

spec.mcpServers

spec:
  mcpServers:
    - name: notes
      route: /mcp
      transport: streamable-http

各 entry は次を持ちます。

field	required	description
name	yes	MCP server 名
endpoint	no	絶対 URL
route	no	app route 上の相対 path
transport	no	現在は streamable-http

endpoint と route のどちらかは必須です。

spec.fileHandlers

spec:
  fileHandlers:
    - name: markdown
      mimeTypes: [text/markdown]
      extensions: [.md]
      openPath: /files/:id

field	required	description
name	yes	handler 名
mimeTypes	no	MIME type 配列
extensions	no	拡張子配列
openPath	yes	open 時に使う app path

OAuth と Takos-managed token

spec.oauth

spec:
  oauth:
    clientName: Notes Assistant
    redirectUris:
      - https://notes.example.com/oauth/callback
    scopes:
      - openid
      - profile
      - spaces:read
    autoEnv: true
    metadata:
      logoUri: https://notes.example.com/logo.png
      tosUri: https://notes.example.com/tos
      policyUri: https://notes.example.com/privacy

field	required	description
clientName	yes	OAuth クライアント表示名
redirectUris	yes	リダイレクト URI 配列 (相対パスは Endpoint の URL を基準に解決)
scopes	yes	要求するスコープ配列
autoEnv	no	deploy 時に OAuth env を自動注入するか
metadata.logoUri	no	クライアントロゴ URL
metadata.tosUri	no	利用規約 URL
metadata.policyUri	no	プライバシーポリシー URL

manifest で OAuth client を自動登録できます。詳細は OAuth を参照してください。

spec.env.required と spec.takos.scopes

spec:
  env:
    required:
      - TAKOS_ACCESS_TOKEN
  takos:
    scopes:
      - threads:read
      - runs:write

TAKOS_ACCESS_TOKEN を要求すると、Takos-managed token を deploy 時に解決できるようになります。権限は spec.takos.scopes で宣言します。

validation で落ちる代表例

• kind が App ではない
• spec.services が空
• build.fromWorkflow.path が .takos/workflows/ 配下ではない
• binding が存在しない resource を参照している
• workflow.service や routes[].service が存在しない service を参照している
• mcpServers で endpoint と route の両方が空

確認方法

takos deploy validate

CLI は repo-local .takos/app.yml を読み、現在の parser と同じ contract で validation します。