Capabilities

A capability is a self-contained, versioned piece of agent functionality. You describe it in a manifest, which is a JSON document, and Keiki turns it into tools, prompt guidance, schedules and stored state for any agent that installs it.

Every feature Keiki ships is a capability too, from the browser to loops and cards. Official capabilities and ones you publish use the same format, so you can build anything Keiki can.

The manifest

In TypeScript, @onkeiki/agents exports the shape as CapabilityManifest (with CapabilityTool, CapabilityLoop, CapabilityEntity, ...); write manifests as { ... } satisfies CapabilityManifest so mistakes fail at compile time rather than at sync. The type is discriminated on runtime: a tool whose run.kind differs from it, a render-template tool without template, or templates on any other runtime is a type error.

{
  "slug": "cards",              // unique per publisher, [a-z0-9-]
  "version": "1.0.0",           // semver; installs pin an exact version
  "title": "Cards",
  "description": "Render swipeable image card carousels and deliver them as one media message.",

  // How the capability's tools run. One of:
  //   render-template  slides rendered to images by the rendering service
  //   openapi          an OpenAPI source plus OAuth (the user-connections path)
  //   codemode         a small program the agent writes over granted namespaces
  //   mcp              an MCP server source
  //   builtin          a Keiki builtin (official capabilities only)
  "runtime": "render-template",

  // The host namespaces this capability may reach. A namespace you do not
  // list here is not available to it.
  "uses": ["loops", "entities"],

  // Secrets the installer provides. They are resolved per call and never handed
  // to code the model wrote.
  "secrets": [
    { "name": "RENDER_SERVICE_URL", "required": false, "description": "Override the shared rendering service." }
  ],

  // The tools this capability adds to an agent.
  "tools": [
    {
      "name": "render_cards",
      "description": "...",
      "inputSchema": { "type": "object", "properties": { /* ... */ } },
      "run": { "kind": "render-template", "template": "story" }
    }
  ],

  // The hosts the `http` namespace may reach (required with uses: ["http"]).
  // A leading "*." matches subdomains. HTTPS only.
  "http": { "allow": ["api.example.com"] },

  // Guidance added to the agent's system prompt while the capability is installed.
  "prompt": "Use render_cards only for genuinely multi-beat stories...",

  // Loop presets registered while installed (requires uses: ["loops"]).
  "loops": [
    { "name": "daily-digest", "scheduleType": "cron", "scheduleExpression": "0 8 * * *", "quiet": true, "prompt": "..." }
  ],

  // The entities this capability stores data in (requires uses: ["entities"]).
  "entities": ["digest_state"],

  // Card templates uploaded to the rendering service for your account
  // (render-template runtime only).
  "templates": [
    { "name": "story", "source": "...tsx source...", "inputSchema": { "fields": [ /* ... */ ] } }
  ]
}

Runtimes

A codemode capability ships no tool code of its own. Its prompt documents the API the agent should call, and the agent writes the calls. The program runs in a confined interpreter. Its only bindings are the namespaces you granted and a safe subset of JavaScript. There is no filesystem, no ambient network, no module loading and no timers. Every call is checked against the tool's input schema and counted against a per-run budget, and a failed run comes back with a stable error kind.

Namespaces

uses decides which host services a capability may reach. A namespace you do not declare is not available.

Declaring sandbox also turns the sandbox on for the agent, so a capability that writes a file can deliver it. browser and mcp stay operator-only. A capability cannot grant itself either one.

HTTP

http.request reaches only the hosts in the manifest's http.allow, only over HTTPS, and never a private address. An entry is a hostname such as api.example.com or *.cdn.example.com, and it covers port 443. Another port needs its own entry, like api.example.com:8443.

Credentials stay on the host. Your code writes {{SECRET_NAME}} placeholders in headers or the body, and Keiki substitutes secrets that the manifest declares. They come from the installer's developer secrets and are redacted from any error it reports. A secret left unset is an error, and the installer has to provide it.

A response can be written straight into the caller's sandbox with save: { to, base64Field? }, either raw or from a base64 field of a JSON response. The call returns its status and where it saved, not the payload.

Installing and publishing

• You publish a capability at a slug and version. It moves from private, through review, to published. Publishing for use outside your own organization always goes through human review. Publishing a capability walks through it, with a prompt for your coding agent.
• An install pins an exact version. Upgrades are manual. Installing a newer version replaces the pin, and nothing upgrades on its own.
• Official capabilities are published by Keiki itself.

Official capabilities

• Cards uses render-template. It renders a template's slides to images and delivers them as one media message, so four or more cards arrive as a swipeable stack on iMessage. If rendering or delivery fails, it falls back to text bubbles. It uses the shared rendering service, and the installer can override its URL and secret. Rich cards covers enabling it and the agent's calling contract.
• Images is a codemode capability with no shipped tool code. Its prompt documents an image-generation endpoint, and the agent writes the request over http. The host supplies the API key, so the code never sees it, saves the decoded PNG into the conversation's sandbox, and the generic file-send tool delivers it. You can publish the same shape against any API.

Feature toggles

The remaining official capabilities are toggles: turning one on attaches a fixed set of built-in tools (or, for the purely behavioural ones, a behaviour) to the agent. They appear in the same Capabilities dialog as Cards above.

• Memory — no tools, purely behavioural. The agent extracts durable facts and preferences about each user from conversations and recalls them automatically in later turns, so it remembers people between conversations. Configure categories and auto-retrieval in Managed features.
• Browser — the agent's web reading. browse sends a cloud browser to read pages and carry out multi-step web tasks on the agent's behalf; browser_handoff hands the live session to the person when only they can act (logging in, CAPTCHAs, payment). Enable it and its handoff options under Managed features.
• Web scraping — search and extraction without a full browser: web_search, scrape_page, crawl_site, scrape_images, and a domain brand lookup. Use it when reading public pages; use Browser when a task needs sessions or interaction.
• Sandbox — a persistent code sandbox per conversation: exec runs commands and download_url fetches a URL into it, so written files can be delivered back to the user. See Managed features for persistence and time limits.
• Loops — scheduled workflows the agent can create and manage for the user: create_loop, list_loops, update_loop, delete_loop, run_loop, and diff_since_last_run. A loop runs its prompt on a cron or interval schedule, and quiet loops send nothing when there is nothing to report.
• MCP Integrations — connect external MCP servers and OpenAPI sources to the agent, and let each user authorize their own account over a texted OAuth link (connect_account). The agent reaches them through mcp_execute. Setup lives in the MCP plugin section.
• Wallet — a spending policy in front of a real payment account: wallet_balance, purchase authorization and status, and a user-card connect flow. Budgets, approvals and the card lifecycle are covered in Agent wallets.
• Computer use — desktop automation through accessibility and pointer/keyboard tools (desktop_look, desktop_act, desktop_click, desktop_type, …). It is mutually exclusive with Browser: an agent runs one or the other.

Sandbox provider

Each agent uses one sandbox provider for both Code and Computer use. Daytona is the default. Freestyle is available when FREESTYLE_API_KEY is configured on the deployment. With FREESTYLE_AGENT_SNAPSHOT_ID configured, Freestyle supports desktop screenshots, pointer input, and keyboard input; accessibility-tree tools are not available. Freestyle does not support host-bound secrets. The protected Freestyle desktop viewer also requires FREESTYLE_FORWARD_AUTH_SECRET. The developer API stores an explicit choice in features.sandboxProvider (daytona or freestyle); omit it or send null to use the platform default.