Skip to content

Creating an App with AI

This guide is for non-technical users who want to ask an AI agent to create a new SCALR app for them.

What you'll get

A fully working web application: - Hosted at its own subdomain — <slug>.localhost in dev, <slug>.${SCALR_PUBLIC_DOMAIN} in production (the public domain is set platform-wide via make set-public-domain; see DEPLOYMENT.md). - Logs in with the same SCALR account you already use (single sign-on across every SCALR app). - Listed in the SCALR app hub (the portal at portal.localhost in dev / portal.${SCALR_PUBLIC_DOMAIN} in prod) for users you've given access to. - Stores its data in its own dedicated Postgres database, isolated from every other app.

How to ask

Open a chat with an AI agent that has access to the SCALR repo and prompt it like:

"Please create a new SCALR app called Invoice Tracker. It should let users add clients, create invoices for them, and mark invoices as paid."

That's it. The agent will:

  1. Read the SCALR AGENT_INSTRUCTIONS.md (in the repo root or any app dir — they're all identical).
  2. Ask you for any missing details (e.g. "should this be a product available to all subscribers, or a client-specific app?").
  3. Run the scaffold script (python3 infra/scripts/new-app.py or make new-app) to create the new app.
  4. Add the data model, API endpoints, and basic UI for what you described.
  5. Verify the app boots (make up) and the smoke test passes.
  6. Tell you the URL — usually http://<slug>.localhost — plus the one manual step left for you: creating the OIDC client in Authentik (the agent prints the exact values to paste).

What makes a good prompt

  • Name the app. Give it a clear, human-readable name.
  • One sentence about what it does. This becomes the app hub description.
  • Mention the main things it tracks. "Clients and invoices" or "events and attendees" — these become the data model.
  • Optional: who can use it. "Available to all subscribers" or "just for our team" or "for client Acme only".

What not to ask for in the first prompt

Save these for follow-up prompts: - Specific UI layouts (the agent will start with a basic one; you can iterate). - Integrations with external services. - Custom branding or theming.

The first version is bare-bones on purpose — easier to verify it works before adding complexity.

After the app is created

You can ask the agent to extend it with follow-up prompts:

"Add a 'Notes' field to invoices." "Make the dashboard show the total amount unpaid." "Add a CSV export button."

When you ask for changes, the agent uses the same AGENT_INSTRUCTIONS.md to know which files to touch and which rules to respect (e.g. it never bypasses the auth middleware, never shares databases between apps, never invents its own routing). You don't need to tell it any of that — the rules live in the repo.

One-time setup the agent can't do for you

There's exactly one manual step the agent can't automate:

  • Creating the OIDC client in Authentik. When a new app is scaffolded, you (the human) need to log in to Authentik (http://auth.localhost in dev) and create a Provider + Application for the new app. The agent prints the exact Client ID and the four redirect URIs you need to paste — it's a 60-second click-through. Walkthrough: Configuring Authentik OIDC.

Once that's done, every future change to the app is something the agent can handle end-to-end.