App manifest reference

This page records the manifest fields the TinyCloud JS SDK accepts and the rules it applies when turning a manifest into a sign-in capability request.

Manifest v1

manifest_version is optional for v1. If it is omitted, the SDK treats the manifest as version 1.

{
  "manifest_version": 1,
  "app_id": "com.tinycloud.notes",
  "name": "Notes",
  "description": "Personal notes synced into TinyCloud.",
  "knowledge": true,
  "defaults": true,
  "permissions": []
}

Complete runtime app manifest

This example is deliberately explicit about app data and secret authority. It disables the default tier, names the default space and prefix, and declares the runtime capabilities the app uses. The composer still adds space-level capability introspection and, by default, account-registry permissions.

{
  "manifest_version": 1,
  "app_id": "com.example.research-notes",
  "name": "Research Notes",
  "description": "Private notes with a searchable index and optional provider sync.",
  "icon": "https://example.com/research-notes-icon.png",
  "appVersion": "1.0.0",
  "space": "applications",
  "prefix": "com.example.research-notes",
  "knowledge": true,
  "defaults": false,
  "expiry": "30d",
  "includePublicSpace": false,
  "permissions": [
    {
      "service": "tinycloud.kv",
      "path": "documents/",
      "actions": ["get", "put", "del", "list", "metadata"],
      "description": "Read and write note documents."
    },
    {
      "service": "tinycloud.sql",
      "path": "search-index",
      "actions": ["read", "write", "schema"],
      "description": "Create and query the note search index."
    }
  ],
  "secrets": {
    "MODEL_API_KEY": {
      "actions": ["read"],
      "description": "Read an optional model provider key."
    },
    "PROVIDER_REFRESH_TOKEN": {
      "scope": "research-notes",
      "actions": ["read", "write", "delete"],
      "expiry": "7d",
      "description": "Manage the provider sync token for this app."
    }
  }
}

The SDK resolves the important entries as follows:

Manifest entry	Space	Resolved path	Runtime call
KV `documents/`	`applications`	`com.example.research-notes/documents/`	`tc.kv.withPrefix("com.example.research-notes/documents/")`
SQL `search-index`	`applications`	`com.example.research-notes/search-index`	`tc.sql.db("com.example.research-notes/search-index")`
Global `MODEL_API_KEY`	`secrets`	`vault/secrets/MODEL_API_KEY`	`tc.secrets.get("MODEL_API_KEY")`
Scoped `PROVIDER_REFRESH_TOKEN`	`secrets`	`vault/secrets/scoped/research-notes/PROVIDER_REFRESH_TOKEN`	`tc.secrets.get("PROVIDER_REFRESH_TOKEN", { scope: "research-notes" })`

secrets declarations request access; they do not contain or create secret values. Store values with tc.secrets.put(...), tc secrets put, or TinyCloud Secrets using the same name and scope. A scoped lookup does not fall back to a global secret: the name and scope together identify one vault entry. The example omits did because an ordinary app manifest grants its signed-in session access. Add did only to a manifest that targets a known backend or agent delegate. If that DID is learned at runtime, compose a separate delegate manifest in application code rather than hard-coding it here.

Fields

Field	Required	Meaning
`manifest_version`	No	Schema version. Missing means `1`.
`app_id`	Yes	Stable app namespace and default path prefix.
`name`	Yes	Human-readable app name.
`description`	No	Human-readable summary of what the app does.
`did`	No	Optional delegate DID target for manifest-driven delegation.
`icon`	No	URL for the app icon shown in permission UI.
`appVersion`	No	Application version metadata.
`space`	No	Default TinyCloud space. Missing means `applications`.
`prefix`	No	Path prefix override. Missing means `app_id`; `""` disables prefixing.
`knowledge`	No	`true` for `knowledge/index.md`, or a root path string.
`defaults`	No	Permission tier selector. Missing means `true`.
`expiry`	No	Default permission expiry, using duration syntax such as `30d` or `2h`.
`permissions`	No	Explicit permission entries beyond the defaults.
`secrets`	No	Secret-name shorthand resolved to encrypted vault KV resources in the `secrets` space.
`includePublicSpace`	No	Whether to include the public-space companion behavior. Missing means `true`.

The TinyCloud App Kit schema also accepts a descriptive top-level resources object for app packaging. The JS SDK manifest composer does not currently read that object when it builds sign-in capabilities; declare runtime authority in permissions, defaults, and secrets instead.

Secret declarations

Use the object form when a secret needs a scope, non-default actions, an expiry, or a user-facing description. The manifest object key is the secret name unless the object sets name explicitly.

{
  "secrets": {
    "READ_ONLY_KEY": true,
    "GLOBAL_TOKEN": ["read", "write"],
    "APP_TOKEN": {
      "name": "PROVIDER_TOKEN",
      "scope": "my-app",
      "actions": ["read", "write", "delete"],
      "expiry": "7d",
      "description": "Token used by the provider sync job."
    }
  }
}

true means read access. Secret actions accept read, write, delete, list, and metadata; the SDK expands them to the backing encrypted vault KV actions. Secret names use upper snake case. Scopes are normalized to lowercase kebab case, and default and global are reserved—omit scope for a global secret.

Permission entries

Each permission entry names a service, optional space, path, and action list. The SDK expands short actions such as get, put, and read into full TinyCloud ability URNs when it builds the recap.

{
  "service": "tinycloud.sql",
  "path": "conversations",
  "actions": ["read", "write"],
  "description": "Read and write normalized conversation records."
}

Rules to keep in mind:

space inherits from the manifest when omitted
space defaults to applications
path is app-relative unless you set skipPrefix: true
skipPrefix: true tells the SDK not to prepend the manifest app_id
expiry can override the manifest expiry for one permission
description is user-facing context and does not change authority
encryption permissions use raw network URNs as the path value

Default tiers

When defaults is enabled, the SDK starts from a standard permission set for the app prefix. Higher tiers add more capabilities:

standard: KV read/write/delete/list/metadata and SQL read/write
admin: standard plus SQL schema
all: admin plus DuckDB read/write

The SDK also adds tinycloud.capabilities/read separately for each requested space so capability introspection stays space-scoped.

Composition rules

capabilityRequest takes precedence over manifest
includeAccountRegistryPermissions defaults to true
manifest composition can add account-registry writes
owned encryption networks can request tinycloud.encryption/network.create when the manifest asks for tinycloud.encryption/decrypt

Source note

The manifest composer, default tiers, and encryption-network behavior are implemented in the JS SDK and covered by sign-in tests. Keep this page aligned with those sources instead of the whitepaper drafts.

Concepts

SDK reference

Protocol reference

Terminology

App manifest reference

Manifest v1

Complete runtime app manifest

Fields

Secret declarations

Permission entries

Default tiers

Composition rules

Source note

​Manifest v1

​Complete runtime app manifest

​Fields

​Secret declarations

​Permission entries

​Default tiers

​Composition rules

​Source note

Manifest v1

Complete runtime app manifest

Fields

Secret declarations

Permission entries

Default tiers

Composition rules

Source note