Pages

A page is a small HTML page in your workspace that LocalAI shows as part of its UI. The assistant writes one when you ask (“make me a task board”), or you write it yourself. A page keeps its data in files next to it, so the assistant can read and change the same data in a chat.

A page runs in a sandboxed frame. It cannot reach the network, the rest of LocalAI, your other files or your other chats. It talks to LocalAI only through a small bridge, window.localai.

Where a page lives

A page is a folder of your home:

pages/
  tasks/
    index.html     the page (required, at most 1 MiB)
    page.json      title, icon, description and widget (optional)
    tasks.json     data files of the page, any name, any subfolder

• The folder name is the page name: lowercase letters, digits and dashes, 1 to 64 characters, starting with a letter or a digit (^[a-z0-9][a-z0-9-]{0,63}$). A folder with another name, or without index.html, is not a page.

• page.json is optional:

  { "title": "Tasks board", "icon": "list-checks", "description": "What I do this week" }

  A missing or broken page.json does not stop the page; the folder name is then the title.

• A widget block in page.json lets the page be a tile on Home (see A page on Home):

  { "title": "Clock", "widget": { "size": "small", "title": "Now" } }

In the UI

• Pages in the sidebar opens the list of your pages. The entry shows only when you have at least one page, and the first time it appears it carries a small New label, until you open it or for a week (switch it off with Notes about new things in Account). Pinned pages show under it.
• The list groups your pages under Yours. Each row shows the title, the description, the folder and when the page changed last and who wrote it (you or the assistant), with Open, a pin toggle (Pin to sidebar) and a menu: Ask the assistant to change this (a new chat with the page’s path in the message box), Show its files (the folder in Files), Rename (moves the folder) and Delete page (moves the folder to the Trash, where Files can restore it). Above eight pages, a filter field shows over the list. Ask for a new page opens a chat with “Make me a page that " in the message box.
• With no pages, the screen offers Ask for a page, and Start from a task board or Start from a reading list, which copy a starter page into pages/task-board/ or pages/reading-list/. The copy is yours; ask the assistant to change it. Two starter pages ship with LocalAI: a task board (task-board, data in tasks.json) and a reading list (reading-list, data in reading.json). Home offers both under Or start from a ready page.
• Open a page to see it at /app/pages/<name>. The strip above it says that the page runs as you, when and by whom it was last updated, and has Reload and Ask the assistant to change this. When the assistant changes index.html, the page reloads. When only a data file changes, the page gets a files.changed event and stays as it is. Switching between the light and dark theme reloads the page too: it gets the theme as data-theme on its <html> element.
• Pins are kept in LocalAI/ui.json of your home, under pinnedPages (a list of page names). A pin or unpin keeps every other key of the file.

How the assistant makes a page

Ask in a chat, for example “Make me a page with a reading list in pages/reading/”. The assistant writes pages/reading/index.html and a data file with its file tools. The page shows up under Pages as soon as the change is saved. To change a page, open it and use Ask the assistant to change this.

One index.html with inline script and style is the simplest page. A page can also keep its script, style sheets, modules, small images and data in files next to it (see Files next to the page). A form cannot be submitted in the sandbox, so a page handles the click of a button and the Enter key itself.

The bridge

Inside the frame, window.localai has these calls. Each returns a promise. A path is relative to the page’s own folder.

Example: a counter that keeps its value in count.json.

<!doctype html>
<button id="b">Count</button>
<script>
  let count = 0
  const b = document.getElementById('b')
  const show = () => { b.textContent = 'Count: ' + count }
  localai.files.read('count.json')
    .then(f => { count = JSON.parse(f.content).count })
    .catch(() => {})   // no file yet
    .finally(show)
  b.onclick = () => {
    count++
    show()
    localai.files.write('count.json', JSON.stringify({ count }))
  }
  localai.on('files.changed', ev => {
    if (ev.paths.includes('count.json')) {
      localai.files.read('count.json').then(f => { count = JSON.parse(f.content).count; show() })
    }
  })
</script>

Your own writes also come back as files.changed. Compare the version you got from write with the one read gives to skip them.

chat.send

chat.send(text) never starts the assistant by itself. LocalAI shows the message above the page with a choice of chat: the page’s own chat (created on first use, titled “Page: