Koyd Apps

What a Koyd app is

A Koyd app is a tool with its own interface that runs inside Koyd: a chart, a tracker, a dashboard, or a larger project tool. The interface runs in a sandboxed frame. An app can add a TypeScript backend that runs on your Koyd Server, keeps durable data there, and offers tools to your sessions. It can also hold private AI conversations of its own.

Backend code and data belong to the server, and the app window is a client. Server features need that instance to be running and reachable.

Create an app

1. Ask an agent in a project session to build the tool you need. Koyd includes the koyd-apps-builder skill and its authoring guides, so agents know the app format.
2. The app appears as a preview in the chat. After the agent changes its files, choose Reload app source in the preview header.
3. If the app has a backend, a banner explains that it runs local Node code with access to your computer and network. Choose Enable backend to run that exact version.
4. Choose Save as app, enter a Name and an optional Description, and choose Save. The app appears in Apps.
5. Enable the saved app’s backend as well. Preview and saved versions have separate approvals, data, and AI history.

Good to know · Changed source needs enabling again. Imported apps never arrive with permission to run.

Open your saved apps

Open Apps from the workspace header, or press Ctrl+Alt+A (Cmd+Option+A on a Mac). Reopening the panel shows your apps right away and refreshes the list in the background.

• Select an app to open it inside Koyd. Choose Back to Koyd or press Escape to return to your chat and draft as you left them.
• Open in separate window opens the app in its own window, titled with the app’s name and with a Back to Koyd link.
• On phones, tablets, and narrow windows, and whenever a window cannot open, the app opens inside Koyd.
• More options holds Rename, App settings, and Delete app.

Browser tabs and installed PWAs use the same paired server connection. An app window stays attached to the instance it was opened from. A link for an instance this device has not paired asks for that instance’s pairing link; it never opens a matching app from another server.

Start, stop, and inspect

The App backend menu in an app’s toolbar, and App settings in the Apps panel, show the backend’s state: Not enabled, Ready to run, Starting, Running, or Stopped. From there you can Start headless to keep it running without a window, Restart or Stop it, read its logs, or disable it.

Opening a window attaches to the same backend. After Stop, Koyd does not restart the backend for tools until you start it again. A backend with no windows, tool users, or active work stops after five idle minutes.

Up to 16 backends and 32 app AI conversations, eight per app, can run at once. Backend calls and AI turns can take up to ten minutes. A server update restarts the server, which stops running backends and app AI turns; see Updating Koyd.

Use app tools in sessions

The tools an app declares become available to sessions automatically once you save the app and enable its backend. There is no separate switch.

1. Save the app and enable the saved version’s backend.
2. Select the app by name in /mcp, in an agent’s configuration, or in the always-on MCP settings.
3. Ask the session to use it. Koyd starts the backend when needed, even with the app window closed.

The app window, its own AI, and your sessions all use the same backend and data.

Models, agents, and resources for app AI

Apps can hold private AI conversations, using the providers already connected in Koyd. Choose AI settings in the app’s toolbar, or in App settings from the Apps panel, to pick the model for new conversations or for the current one. The list shows the models enabled in Koyd’s model settings with each enabled reasoning level, and Use Koyd default follows your default model. For an app with a backend, enable the backend first.

Manage shared providers in the same dialog connects or disconnects providers for all of Koyd, not only this app. Apps never receive provider credentials. If a chosen model becomes unavailable, the app reports an error instead of switching to another provider.

Under Agents, skills and MCPs, choose an agent from this instance and add skills and MCP connections. Include Koyd’s always-on skills and MCPs is on by default. The agent brings its instructions and resources, and its model takes priority for new conversations. Changing the model or resources of an existing conversation keeps its history.

• Read only agents get no MCP tools, and only app tools that the app marks as read only.
• YOLO agents can use the selected MCP connections and all of the app’s declared tools.

App conversations stay private to the app. They do not appear in the session sidebar, do not delegate to other agents, and do not get Koyd’s coding tools.

Edit, import, and share

To change an app, type /apps in a chat and choose it. Koyd restores its saved source for editing and keeps the previous source folder in koyd-apps/.backups for recovery. The Apps panel can also search, rename, import, export, and delete apps. Exports contain app source, not runtime data, AI history, or permission to run.

App settings → Download app shortcut gives you a link to the saved app on the current device. It still needs the right server connection and pairing. It does not bundle the backend or install a standalone offline program.

Apps shared through a team you joined show a Team: <name> badge and are read-only here. The Teams (beta) guide explains how shared resources are reviewed.

App styling and themes

Each app owns its look. Koyd does not pass its theme, fonts, or CSS into the app, so switching Koyd’s theme never restyles or reloads an app. Include the styles in the app source; otherwise browser defaults apply. An app with a transparent background gets a stable white backdrop.

Older apps that relied on Koyd’s theme variables or helper classes need to define those styles themselves. Koyd does not rewrite saved source.

Client and backend APIs

Apps use Koyd’s app SDK for their interface and runtime features. A backend has one entry file, server.ts or server/index.ts. It declares handlers and optional MCP tools with defineServer, and the client calls those handlers through createServerClient. Backend source never reaches the browser. The built-in authoring guides cover the full SDK.

Backend packages are installed from package.json with install scripts turned off, so packages that need native compilation must ship prebuilt. App source is limited to 16 MB and 2,000 files.

Client-only apps

An app can stay entirely in the browser when it needs no backend. Add a backend when you need durable server work, npm packages on the server, or tools for your sessions. A client-only app does nothing in the background while its window is closed.

Data and trust

App runtime data lives on the selected server. Preview and saved versions keep separate backend data and AI histories, while the older key-value storage API still shares one storage ID between them. Removing an app revokes its permission to run and stops its backend; its durable data stays on disk.

Good to know · An enabled backend is trusted Node code with access to your computer and network, and process separation is not a security sandbox. Review app source and dependencies before you enable it, and keep secrets out of app source and exports.