> ## Documentation Index
> Fetch the complete documentation index at: https://trytilde.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Spaces and Live

> Build React spaces in the ontology project, fed only by its reads, actions, and realtime views, and open them in Live under the ontology's policies.

A space is an interactive app built on your ontology: a React page in the project repository that shows live data, runs actions, and can be embedded in your own product, always under the ontology's policies. It gets data only from the ontology's handlers, through a typed client that Tilde generates from your ontology. It never runs SQL. When a page needs new data, add a read to the ontology in the same change.

**Live** is where people use an ontology in Tilde Cloud. It lists the spaces they may open, and their chats with agents.

## Add a space

Spaces live in `spaces/`, an npm project next to `ontology/`. Each folder is one space.

```text theme={"system"}
spaces/
  package.json
  pipeline/index.tsx
  customers/index.tsx
```

```json spaces/package.json theme={"system"}
{
  "private": true,
  "type": "module",
  "dependencies": {
    "@bufbuild/protobuf": "^2.10.0",
    "@connectrpc/connect": "^2.1.0",
    "@connectrpc/connect-web": "^2.1.0",
    "@tailwindcss/cli": "^4.1.0",
    "react": "^19.1.0",
    "react-dom": "^19.1.0",
    "recharts": "^3.2.0",
    "tailwindcss": "^4.1.0"
  }
}
```

`@tilde/spaces` is provided at build time, like `@tilde/ontology`, so it is not listed.

A page default-exports a component, and exports a `title`.

```tsx spaces/pipeline/index.tsx theme={"system"}
import { addCustomerNote, customerActivity, invoiceGrid, pipelineSummary } from "@tilde/contract";
import { DataGrid, MetricTile, Page, useAction, useGridState, useRead, useRealtime } from "@tilde/spaces";

export const title = "Pipeline";

export default function Pipeline() {
  const summary = useRead(pipelineSummary, { input: {} });
  const acme = useRealtime(customerActivity, { key: "acme", input: {} });
  const note = useAction(addCustomerNote);
  const grid = useGridState({ pageSize: 25 });
  const page = useRead(invoiceGrid, { input: { page: grid.state.page, pageSize: grid.state.pageSize } });

  return (
    <Page title={title}>
      <MetricTile label="Outstanding" value={summary.data?.outstanding} />
      <DataGrid
        columns={[{ key: "invoiceId", label: "Invoice" }, { key: "amount", label: "Amount" }]}
        rows={page.data?.rows}
        total={page.data?.total}
        grid={grid}
        rowKey={(r) => r.invoiceId}
      />
      <button onClick={() => note.run({ key: "acme", input: { requestId: crypto.randomUUID(), body: "Called" } })}>
        Log a call
      </button>
    </Page>
  );
}
```

* `@tilde/contract` exports one typed reference per handler. Importing a handler that does not exist is a build error.
* `useRead(handler, { key?, input })` calls a read again when its request changes, or on `refetch()`. It does not poll. Use a realtime view for live data.
* `useRealtime(handler, request)` subscribes to a realtime view, and reconnects on its own.
* `useAction(handler)` returns `run(request)`, which resolves with the action's outcome, including **pending approval**.
* The kit includes `Page`, `Grid`, `Card`, `MetricTile`, `DataGrid` with `useGridState`, `FilterBar`, `Chart`, and `ErrorNote`, with a Tailwind preset for light and dark themes. `DataGrid` passes paging, sorting, and filters to your read, so the server does the work.

Tilde installs `@tilde/contract` and `@tilde/spaces` when it builds the project. Every deploy builds and publishes the spaces with the ontology.

## Who can open a space

Opening a space is a Cedar decision, like any other:

```ts theme={"system"}
import { cedar, space, group, openSpace, policy } from "@tilde/ontology";

policy("sales-open-pipeline", cedar`permit(principal in ${group("sales")}, action == ${openSpace}, resource == ${space("pipeline")});`);
```

The space id is its folder name. Separately, each call the page makes is decided by that handler's own policies, and a space can call only the handlers its code uses. Removing someone's access takes effect within five minutes.

## Open spaces in Live

**1. Serve the environment in Live**

Switch on **Serve its spaces in Live** when you create the environment.

**2. Grant access**

Give people `view` on the project, and an `openSpace` policy for each space.

**3. Open Live**

People select **Live**, then the space. Tilde opens it for their own identity, so every call is decided as `user:<id>`.

## Roll back a space

The project's **Spaces** tab lists each space's versions per environment. Activate an earlier version to roll back one space without redeploying the ontology. An unchanged space keeps its version across deploys.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.