web-app-sdk

Orkas Web App SDK

Build browser interfaces against the host SDK. Keep credentials, account identity, file paths and permission decisions in Orkas. Do not import Electron, forward arbitrary IPC or copy the Agent runtime into the app.

Find the actual contract

Read the API reference before choosing methods. It contains the executable registry's input schemas, result shapes, examples and unsupported families. Read the starter HTML and its manifest when starting a bundle or checking integration. These files are copyable inputs, not an executable Skill script.

The model's own tools are not Web APIs. tools.list in a running app lists only eligible existing executors; never invent SDK methods from host tool names.

Build and discover

1. Put orkas-app.json at the app bundle root. Set sdkVersion: 1 and declare only needed families from storage, appFiles, files, ai, library, connectors.
2. Load <script src="/__orkas/sdk.js"></script> before app code. Use window.orkasApp. Local bundles and external HTTP(S) scripts, styles and assets are supported in running apps and previews.
3. Call capabilities.list() to check support, declaration, availability and authorization separately. Use capabilities.describe({method}) for the current schema. Never treat a declaration or discovery result as consent.
4. Use api.<group>.<method>(arguments, {signal, onProgress}). Both options are optional; AI progress delivers text deltas. Render untrusted results with textContent, not HTML. Inspect tool isError and AI stopReason.
5. Deliver through the existing interactive-result or saved-app workflow and verify there. A loose HTML export or ordinary browser has no Orkas bridge.

Capability boundaries

• Storage: JSON values private to this account and app source. Set scope: "cloud" for business data to participate in the account's existing cloud sync; use scope: "local" for caches. Omitted scope remains local for old apps. There is no automatic migration from local or browser storage.
• App files: declare appFiles for relative-path text/binary files in the app's private sandbox. Its default scope is cloud; choose local for caches. Read/write/list/remove affect only this app. Source code is separate. Reopening keeps data; copied/re-saved apps have independent sandboxes. Cloud sync requires the same account and sync enabled on each device. Saved means persisted on this device, not uploaded. Conflicts use Orkas Settings; there is no SDK sync-status API. Keep explicit export for important data. Preview redirects both scopes to disposable storage; it cannot prove sync.
• Files: native selection returns an opaque handle to a read-only snapshot, not a path or permission to edit the original. Release handles after reading. Picker/save cancellation returns null. Text export creates a new file; an existing destination is refused. Orkas managed data cannot be selected.
• AI: configured model, supplied prompt only; no implicit conversation, project, Agent, tools or Skill context. Ordinary generation needs no separate app permission dialog. Requests can incur model charges; usage reports tokens, not price. Show partial output as incomplete when stopReason is max_tokens.
• Library: eligible global Library operations without a separate app consent. There is no inferred project binding from the source conversation.
• Connectors: discover tools.list(), then call its list_connector_tools executor to obtain enabled connector/action schemas before invoking call_connector_tool. Existing operation permissions apply: sensitive actions use the Orkas dialog; Trusted runs available actions without confirmation. Allow for this use covers the approved connector account and sensitive action class until this app instance closes. Other apps and reopened instances do not inherit it. External writes and fees are possible; inspect business errors. Connector installation is not exposed.