# The local loop (running your app on your own machine)

> Everything the `osy` CLI does to the project in front of you — run it, look at what it did, check it before you ship. The first-day mistake is treating a local platform as a database you can leave data in: a compile mints a new app version and yesterday's rows are not what the new one reads, so seed through the app's own functions or `osy import` after every compile.

<!-- id: local-index · area: local · stability: stable · html: https://osysharp.com/reference/local/index/ -->

## Summary        {#summary}
**`osy` is the local surface: it works on the project in front of you, needs no account and no cloud.** Most of it
is offline. It runs against a local platform it starts for you on demand, and the whole area is one loop — write,
run, look, check.

```bash title="the loop, in four verbs" syntax
osy launch      # create the app if missing, compile this source into it, open it
osy logs --tail # what it said — client and server lines under one correlation id
osy inspect     # what actually happened in a run, and where it faulted
osy check       # validate + lint + test, one verdict, before you ship
```

## Description    {#description}
**A compile mints a new app VERSION, and data does not carry across it.** This is the fact that surprises people
first: a recompile is not an edit in place, so rows you created against the previous version are not what the new
one reads. Seed through the app's own functions, or [Importing data](https://osysharp.com/reference/local/importing-data/), after a compile — never by expecting
yesterday's data to still be there.

**A local platform is a cache, not a store.** Instances live under `~/.osy/instances/`, each carrying its own
Postgres cluster, and they are reaped: one you have not touched for a day is gone, and that is correct — losing one
costs a rebuild. [Listing your local platforms](https://osysharp.com/reference/local/listing-local-instances/) shows every instance on the machine and which are running;
[Reclaiming the disk your local platforms use](https://osysharp.com/reference/local/reclaiming-local-disk/) is the deliberate sweep. [Stopping the local platform](https://osysharp.com/reference/local/stopping-the-local-platform/) ends the one serving
this project.

**Ask the platform rather than reading the compiler.** Most questions about *your app* have a verb:
[Understanding your app](https://osysharp.com/reference/local/understanding-your-app/) for the resolved model, [Explaining your app's security](https://osysharp.com/reference/local/explaining-your-app/) for the declared security in
plain English, [Reading a capability's source](https://osysharp.com/reference/local/reading-a-capability/) for what a surface offers, [Reading your theme](https://osysharp.com/reference/local/reading-your-theme/) for the token vocabulary you may write, [Mapping your theme onto your kits — osy kit tokens --app](https://osysharp.com/reference/local/mapping-your-theme-onto-your-kits/) for what each token comes to once your kits are in it. A question you answer by reading source is
a question the platform has not answered yet.

**When something misbehaves, look before you reason.** [Seeing what happened when your code ran](https://osysharp.com/reference/local/seeing-what-happened/) opens the trace and jumps to
the fault; [Recording a run](https://osysharp.com/reference/local/recording-a-run/) captures one deliberately; [Seeing what a page cost](https://osysharp.com/reference/local/seeing-what-a-page-cost/) answers the
performance question. Faults are captured even with tracing off.

## The pages      {#the-pages}
Run `osy docs local` for the full listing.

- **The loop itself** — [Starting a project](https://osysharp.com/reference/local/starting-a-project/), [The inner loop](https://osysharp.com/reference/local/the-inner-loop/), [Running a local platform](https://osysharp.com/reference/local/running-a-local-platform/),
  [Stopping the local platform](https://osysharp.com/reference/local/stopping-the-local-platform/), [Installing the editor extension](https://osysharp.com/reference/local/installing-the-editor-extension/), [Upgrading the toolchain](https://osysharp.com/reference/local/upgrading-the-toolchain/)
- **Getting your app running** — [Launching your app](https://osysharp.com/reference/local/launching-your-app/), [Launching the page you're on](https://osysharp.com/reference/local/launching-the-page-youre-on/),
  [Compiling your app](https://osysharp.com/reference/local/compiling-your-app/), [Adding an account](https://osysharp.com/reference/local/adding-an-account/), [Setting an account's password](https://osysharp.com/reference/local/setting-an-accounts-password/),
  [Giving a secret its value](https://osysharp.com/reference/local/giving-a-secret-its-value/)
- **Getting data in and out** — [Importing data](https://osysharp.com/reference/local/importing-data/), [Importing a data source's schema](https://osysharp.com/reference/local/importing-a-schema/), [Running a function](https://osysharp.com/reference/local/running-a-function/),
  [Reading your data](https://osysharp.com/reference/local/reading-your-data/)
- **Building a provider** — [Generating the C# a native provider implements](https://osysharp.com/reference/local/generating-a-seam/)
- **Looking at it** — [Photographing a page](https://osysharp.com/reference/local/photographing-a-page/), [Seeing what happened when your code ran](https://osysharp.com/reference/local/seeing-what-happened/), [Recording a run](https://osysharp.com/reference/local/recording-a-run/),
  [Seeing what a page cost](https://osysharp.com/reference/local/seeing-what-a-page-cost/), [Reading what your application actually used](https://osysharp.com/reference/local/reading-what-your-app-used/)
- **Asking about it** — [Understanding your app](https://osysharp.com/reference/local/understanding-your-app/), [Explaining your app's security](https://osysharp.com/reference/local/explaining-your-app/),
  [Reading a capability's source](https://osysharp.com/reference/local/reading-a-capability/), [Reading your theme](https://osysharp.com/reference/local/reading-your-theme/), [Mapping your theme onto your kits — osy kit tokens --app](https://osysharp.com/reference/local/mapping-your-theme-onto-your-kits/)
- **Designing it** — [Looking at a reference site before you design](https://osysharp.com/reference/local/looking-at-a-reference/), [Finding a typeface by its character, and shipping it](https://osysharp.com/reference/local/finding-a-font/), [Finding licence-clear photographs past the stock picks](https://osysharp.com/reference/local/finding-photographs/), [Checking whether a theme is a stock look](https://osysharp.com/reference/local/checking-a-look/)
- **Before you ship** — [Checking your app](https://osysharp.com/reference/local/checking-your-app/), [What a clean check means](https://osysharp.com/reference/local/what-a-clean-check-means/), [Checking every project at once — osy validate --all / --affected](https://osysharp.com/reference/local/checking-every-project/), [Checking access](https://osysharp.com/reference/local/checking-access/), [Drilling your app](https://osysharp.com/reference/local/drilling-your-app/)
- **Shipping it** — [Deploying your app to an environment](https://osysharp.com/reference/local/deploying-your-app/) · [Publishing a project to Osyrin](https://osysharp.com/reference/local/publishing-to-osyrin/) (`osy link`, and Publish in Studio) · [Signing in to Osyrin](https://osysharp.com/reference/local/signing-in-to-osyrin/) (`osyrin login`)
- **Housekeeping** — [Listing your local platforms](https://osysharp.com/reference/local/listing-local-instances/), [Reclaiming the disk your local platforms use](https://osysharp.com/reference/local/reclaiming-local-disk/)

## See also   {#see-also}
- [The inner loop](https://osysharp.com/reference/local/the-inner-loop/) — the loop end to end, for a person and for an agent at the CLI
- [Launching your app](https://osysharp.com/reference/local/launching-your-app/) — create, compile and open in one verb
- [The browser for screenshots](https://osysharp.com/reference/local/the-browser-for-screenshots/) — `osy browser`: what `--pixels` needs, installed once for every project
- [Opening Studio](https://osysharp.com/reference/local/opening-studio/) — `osy studio`: describe an app in your browser and your own Claude Code builds it
- [What a clean check means](https://osysharp.com/reference/local/what-a-clean-check-means/) — what a green `osy check` does and does not prove