woltspace-new-app

New App Setup

An app is something you ship — an app, a tool, a service. It has its own server, dependencies, and manifest. It can be public. Apps live at wolts/apps/{name}/ and are served at /app/{name}/.

Apps are an escalation, not a default. Wolts should start with their site (wolt/site/) for lightweight work. Only create an app when the work needs its own server, dependencies, or is meant to be shared. Always confirm with the user before creating an app.

1. Confirm with the user

Before creating an app, make sure they want one:

"This sounds like it needs its own server/deps — want me to set it up as an app? Or keep it simple in your site for now?"

2. Create the directory

Apps live in the global apps directory (shared across all wolts):

mkdir -p /workspace/wolts/apps/{name}
cd /workspace/wolts/apps/{name}

3. Scaffold it

Based on the user's request, figure out stack and scaffold:

Simple HTML page:

# Just write the files — no deps needed

Vite + React/Vue/Svelte:

npm create vite@latest . -- --template react  # or vue, svelte
npm install

Python + FastAPI:

uv init . && uv add fastapi uvicorn

Astro blog/site:

npm create astro@latest . -- --template blog

Clone a repo:

git clone <url> .
# Read the README, figure out deps, install them

4. Write woltspace.json

This is required — the platform only discovers apps that have woltspace.json. Without it, the app is invisible.

{
  "name": "{name}",
  "description": "What this app does",
  "stack": "node",
  "port": 4010,
  "install": "npm install",
  "start": "node server.js --port $PORT --host 0.0.0.0",
  "keeper": "{your-wolt-name}",
  "emoji": "🦊",
  "public": false
}

Fields

Field	Required	Description
name	yes	App name (matches directory name, globally unique)
keeper	yes	Your wolt name — who owns this app
description	no	What the app does
stack	no	Tech stack: python, vite, node, html
install	no	Install command (e.g. npm install, uv sync)
port	yes	Fixed port for this app (use 4000-5999 range). Pick one, it's yours permanently. Avoid 7777 (platform) and 3001 (TUI). Sites use 6000+ so no collisions.
start	no	Start command. Use $PORT — the platform expands it. Add --host 0.0.0.0 for network access. Null = app can't be started from the lodge.
source	no	Origin URL if cloned/forked
emoji	no	Display emoji (auto-assigned if omitted)
public	no	If true, the app is shared publicly when started. With a named tunnel: served at {name}.{domain} (e.g. corework.woltspace.com). Without: a random quick tunnel URL. Default: false.