vibes.diy/docs Make an app → Discord
creator docs · how it works · the trail

Read an app's trail

Every app on Vibes DIY keeps the records it needs to work: its source at every version, its rules, the conversation that built it, its data, and the accounts it was allowed to use. Here is where each one lives, who can read it, and the command that opens it.

An app on Vibes DIY is small enough to read. It has one job, a few files, its own database and its own address, and the work of the app runs through records you can open. Together they answer the questions worth asking of any software you let near your inbox or your group chat: what is it, what can it reach, who made it, and how.

This page lists each record, where it lives, who can read it, and the command that opens it. The commands use the CLI; you/potluck stands for any app, written as handle/app-slug.

Before you start

The commands run with npx, so Node.js is the only thing to install.

shnpx vibes-diy login    # once per machine; opens a browser to sign you in

Swap you/potluck for the app you want to read. An app's address shows both halves: vibes.diy/vibe/og/pickathon-picker is the app og/pickathon-picker. More on naming in Name the app in full, and on signing in from a remote machine in Agents and sandboxes.

The records, at a glance

The question The record How to open it
What is it? The source, at every version versions, pull
What can it reach? access.js, backend.js and the outbound policy pull, then read two files
How was it built? The build conversation codegen-log
What was it asked? The app's own AI chats app-chats
What does it hold? Its data, as it stands and as it changes db query, db get, db subscribe
What was it allowed? The consent card behind each connected account Settings, under Connected accounts

The source, at every version

Every release of an app is kept. Publishing adds a new release and leaves the earlier ones where they were.

shnpx vibes-diy versions you/potluck             # every release, ● marks the live one
npx vibes-diy pull you/potluck --version v3    # exactly what the menu calls v3
npx vibes-diy pull you/potluck --published     # what is live right now

versions prints one line per release with its id and its place in the sequence, and marks the one that is live. On your own app the list includes your drafts. pull writes that release's files into a folder named for the app, or into --dir when you give one.

The version labels match the version menu on the app's page, so "v3" means the same release in both places. The details are in Versions, publish, unpublish.

The rules

Two files and one policy decide what an app can reach.

  • access.js decides who can see and change each record. It runs on our servers each time something is saved, and every read is checked against what it decided. The app's own page code has no way around it. The one reader with more is the owner, whose CLI reads of their own app see every record. Start with the access model, then two layers of access, and keep the Access API reference open while you read a real file.
  • backend.js decides what the app does on its own: on a schedule, when a record changes, or when a request arrives. See Your app has a backend.
  • The outbound policy decides which outside services a backend may call, and our servers enforce it on every request. It is written down in Outbound fetch.

Both files come down with pull. Most access.js files fit on one screen.

Three things to look for when you read one:

  • Who can write. The function receives each save and either accepts it or refuses it. Look for what it checks about the person saving: signed in, the author of the record, the owner, a member.
  • Who can read. Each accepted record is placed in channels, and people are granted channels. A record in a channel only its author holds is private to them.
  • What the backend calls. Search backend.js for fetch(. Each address it names has to pass the outbound policy before the request leaves.

An app with no access.js is flat: everyone who can open it can read every record in it. An app with no access function is flat covers what that means.

How it was built

The build conversation is the exchange between the builder and the model that wrote the app.

shnpx vibes-diy codegen-log you/potluck                              # list the build chats
npx vibes-diy codegen-log you/potluck <chat-id>                    # one chat's prompts
npx vibes-diy codegen-log you/potluck <chat-id> --response --user  # a prompt with the model's reply

The list shows each build chat with its id. A chat id alone prints the prompts the builder typed, in order, which is the quickest way to see what an app was asked to be. With --response you get what the model wrote back, and --files shows the files that turn produced.

Add --turn to pick a turn other than the newest. Every flag is in the codegen-log reference, and How a build flows explains what you are reading.

The build conversation belongs to the builder. The people who use an app can read its source and never its prompts, and a developer you add sees their own build chats.

The other half of the build is what the model was given. npx vibes-diy system prints the base system prompt and npx vibes-diy skills lists every skill guide it can load, the same documents published as the generator's reference and described in The system prompts.

What it was asked

Some apps have an AI of their own. Those conversations are kept apart from the build conversation, because they answer a different question: what the app was asked while it was running.

shnpx vibes-diy app-chats you/potluck             # list the chats your account holds
npx vibes-diy app-chats you/potluck <chat-id>   # read one

What it holds

An app's data lives in its own database, scoped to that app.

shnpx vibes-diy db list --vibe you/potluck                   # its databases
npx vibes-diy db query _id --vibe you/potluck --db dishes  # its records, by id
npx vibes-diy db subscribe --vibe you/potluck --db dishes  # each change, live, as it lands

On your own apps you read as the owner. On someone else's you read as yourself, under that app's access.js, and see what any visitor with your access would see. Both cases are covered in Reading your own vibes, and reading someone else's, and how the data moves between devices is in Local-first data and sync.

db list names the app's databases, and most apps have one or two. db query takes a field name and returns the records that have it, so _id returns them all. db get with an id prints one record in full. db subscribe stays open and prints a line each time a record changes, which is a good way to watch what an app does when you press a button in it.

An app that wants a history of its own actions, such as each call it makes to another service, saves a status record for each one. The doc-status state machines pattern shows the shape.

What it was allowed

When an app wants one of your accounts, it asks ahead of time on a consent card. The platform draws the card from the app's published declaration, so the sentence you read and what the backend can later do always agree. The platform holds the key, and the app's code never sees it. The card is shown in full in What the visitor sees.

Everything you have connected is listed in your Settings, under Connected accounts, with a button to stop one app and a button to disconnect a provider altogether. See Expiry, revocation, and what stops.

Who can read what

Record Who can read it
Source, access.js, backend.js Anyone who can open the app while Allow remixing is on, which is the default. With it off: the owner, developers and invited editors. See Keep your code private.
Build conversation The builder. A developer sees their own build chats.
The app's AI chats The account that holds each chat.
Data Whoever the app's access.js lets in, record by record.
Connected accounts The person who connected them.

Read an app someone else made

The same commands work on any app you can open, and they show you what a visitor is allowed to see. With Allow remixing on, that includes the source and the rules.

shnpx vibes-diy versions og/pickathon-picker
npx vibes-diy pull og/pickathon-picker --published --dir ./picker
npx vibes-diy db list --vibe og/pickathon-picker

Open ./picker/access.js first. It tells you what the app will accept from you and what it will show you before you type anything into it. A read the rules don't allow answers Access denied, which is the rules working.

Start with an app you made

shnpx vibes-diy codegen-log you/your-app
npx vibes-diy versions you/your-app
npx vibes-diy pull you/your-app --published --dir ./your-app

Then open access.js and read who can see and change your app's data.

Go deeper