Getting Started

Install Koyo, create a project, and open it in your browser within a minute.

Requirements#

  • Python 3.11 or newer.
  • The runtime dependencies are Starlette, Uvicorn, watchfiles, typer, and tomlkit. They install automatically.
  • No JavaScript framework is required and no Node runtime is needed to run the app. The optional Tailwind CLI powers styling.

Installation#

pip install koyoapp

Create a project#

koyoapp create my-app
cd my-app

Pass a dot to scaffold into the current directory: koyoapp create .

A new project looks like this:

my-app/
  app/
    layout.py        # root layout, wraps every page
    page.py          # routes to /
  components/        # reusable UI components
    landing.py       # animated hero with the docs call to action
    counter.py       # session counter powered by use_state
    site.py          # footer with the docs link
  public/            # static files served at /
  styles/
    globals.css      # compiled to styles/koyo.css
  koyo.config.py     # PORT and PROJECT_NAME
  pyproject.toml     # dependencies managed by the CLI
  package.json       # Tailwind tooling (styling only)
  tailwind.config.js

Run the dev server#

koyoapp dev

Open http://localhost:2309 in your browser. The server prints Local and Network URLs, compiles Tailwind automatically, and patches the page in place when you edit files, without a full reload.

Change the port with --port 8000 or by setting PORT in koyo.config.py. The flag always wins, then PORT, then the default 2309. If the port is already in use, the next free port is used automatically.

The server binds all interfaces by default, so localhost and phones on your network both work. Restrict it with --host 127.0.0.1 if you prefer.

Next steps#