Build Apps for everyone

An App is a small web App with an optional typed backend. You build it from a git repository. On an Oyster or a Fungi Team, people open it in a window and agents call its methods. Share the repository so other builders can install their own copy on Oyster.

What you build

• A page. HTML, or React with Caps components. Ordinary App pages run in sandboxed frames. The chosen home shell, such as Tourtois, instead runs in the top-level host document with elevated host permissions. Choose a shell you trust.
• An optional backend. Typed methods with an input and output schema. Each installed App gets its own SQLite database and only the access it declares, such as git, a Computer, Workflows, Agents or media.
• A package.json declaration. fungi.app names the App and the access it asks for. fungi.build says how to build it.

Agar is the contract: it connects your page to its host and defines your backend methods.

How an App lives

Here is the manual pack-and-install path:

On this manual path, building a Release does not put it in use. The owner installs it, and replacing a Release keeps the App’s data. A registered Bonsai App can instead build and install an accepted main push automatically within permissions the owner already approved. New permissions require owner consent. On Fungi Hub, the owner publishes a built Release of a Team App fork.

Your first App

On a local Oyster, the smallest App is one committed HTML page and a package.json:

hello-app/package.json

{
  "name": "hello-app",
  "private": true,
  "fungi": { "app": { "displayName": "Hello", "capabilities": [] } }
}

Commit it, then pack that commit into a Release and install it with packRelease and installRelease from @fungi.computer/oyster/pack. Step 4 of the agent quick start has the full script and the expected output. To change the App, commit again and run the script again. Oyster switches to the new Release and keeps the data.

Add a backend

The Notes example App has typed methods and its own SQLite. A backend definition looks like this:

TS

import * as z from "zod";
import {
  defineAppBackend,
  defineAppMethod,
} from "@fungi.computer/agar/backend-definition";

export const appBackend = defineAppBackend({
  methods: {
    greet: defineAppMethod({
      description: "Return a greeting without accessing Team resources.",
      effect: "read",
      requires: [],
      input: z.strictObject({ name: z.string().min(1).max(64) }),
      output: z.strictObject({ greeting: z.string() }),
      handler: async ({ name }) => ({ greeting: `Hello, ${name}` }),
    }),
  },
});

The build reads this definition and writes the App’s API for you. Agents find the method and call it as env.<APP>.greet({ name }).

Share it

Where	How
Any Oyster	Share your git repo. An owner clones it, packs a commit and installs the Release, or pushes it to Bonsai and chooses Settings → Make this an App. After that, each accepted push to main builds and installs the new commit, within the access the owner already approved.
A Fungi Team	Fork a platform App, build it on a Team Computer, preview it and accept it. See Build an App and Publish an App.
Bazaar	A Team owner lists a published Release for free or a one-time price. Other Teams find and install it. See Find, install and sell Apps.

An App never gets more access by being installed. The owner approves each capability, and can change that later.

oyster install-apps installs the seven starter Apps, not one arbitrary repository URL. Its --repositories option selects a base URL for those seven repositories, not a single shared App. To install an App from a shared repo, follow the pack and install example or use oyster install ./dist --installation-id my-app after packing it. There is no Oyster App directory yet; Bazaar is a Fungi Hub Team App.

What you can build

Every App below is real and open source. Read its repository to see how it uses the contract.

App	What it shows you how to do	Source
Hello	The smallest App: one committed HTML page	Agent quick start, step 4
Notes	Typed backend methods and the App’s own SQLite	examples/notes-app
Folder list	A Caps page that asks permission and lists a Computer’s files	Build an App
Bonsai	Git repositories, forks and merges through the git binding	fungi-computer/bonsai
Trellis	Workflows of App methods, started by a push, webhook or schedule	fungi-computer/trellis
Grove	Agent conversations that call other Apps	fungi-computer/grove
Shed and Inkcap	A terminal and an editor on a Computer	shed, inkcap
Prints	Images and video from a prompt	fungi-computer/prints
Tourtois	A whole desktop shell that opens every other App	fungi-computer/tourtois