Hello World¶

This walkthrough starts the hub from a local clone, installs the bundled hello-world example app, and opens it in your browser. It covers the end-to-end flow you'll repeat for every app you develop or test locally.

Developer workflow

This page assumes you have completed the Local Setup. The examples/hello app is part of the source tree and is not distributed with the PyPI package.

1. Start the Hub¶

sqb start

The hub starts on http://127.0.0.1:9100 by default. You should see log output similar to:

INFO:     Squareberg Hub starting on 127.0.0.1:9100 — 1 app(s) registered.
INFO:     Started server process [12345]
INFO:     Uvicorn running on http://127.0.0.1:9100

Foreground process

sqb start runs the hub in the foreground. Open a second terminal for the commands below, or see Running as a Service for background operation.

2. Check Status¶

In a second terminal:

sqb status

Expected output:

Hub: running at http://127.0.0.1:9100

  Registered Apps
 ─────────────────────────────────────────
  Name    Version  Status   Description
  hello   0.1.0    stopped  A minimal example app for testing the Squareberg hub

The hello app is already registered (the hub found its manifest during startup) but not yet running because its backend process hasn't been started.

3. Install the Hello App's Dependencies¶

The hello app's backend needs its own Python dependencies installed into its venv. The quickest way is to let sqb app add handle everything:

sqb app add examples/hello

This copies the app into ~/.local/share/squareberg/apps/hello/, creates its .venv, installs the backend, and builds the active frontend.

Already have a copy?

If the hello app already exists from a previous run, remove it first:

sqb app remove hello
sqb app add examples/hello

Alternatively, you can install manually:

uv venv examples/hello/.venv
uv pip install -e examples/hello/backend --python examples/hello/.venv/bin/python

4. Start the Hello App¶

sqb app start hello

The hub spawns a uvicorn process for the hello backend on a Unix socket, waits for the socket file to appear, then marks the app as running.

Verify with:

sqb status

The hello app should now show running.

5. Open the App in Your Browser¶

http://127.0.0.1:9100/apps/hello/

You should see the hello-world frontend. The hub is serving the pre-built static files from the app's frontend/default/dist/ directory.

6. Browse the API Spec¶

The hub exposes each app's live OpenAPI spec:

http://127.0.0.1:9100/registry/hello/spec

This returns the raw OpenAPI JSON generated by FastAPI. You can also use FastAPI's built-in Swagger UI by pointing your browser at the app's socket directly while it is running, or by configuring a tool like Swagger Editor to load the spec URL above.

Summary¶

Step	Command	What happens
Start hub	`sqb start`	Hub scans installed apps and `examples/`, starts on port 9100
Check status	`sqb status`	Lists registered apps and their runtime state
Install app	`sqb app add examples/hello`	Creates venv, installs deps, builds frontend
Start app	`sqb app start hello`	Spawns uvicorn on Unix socket, proxied by hub
View app	browser → `/apps/hello/`	Hub serves frontend static files
API spec	browser → `/registry/hello/spec`	Hub proxies `/openapi.json` from app socket

Stopping everything

To stop the hello app: sqb app stop hello

To stop the hub: sqb stop (or Ctrl-C in the terminal running sqb start)