App names and URLs

Every app gets a short, shareable URL built from your handle and the app's own name, and both are yours to change.

How your app gets its URL

Every app works the moment it’s created. A brand-new app is live at charm.ing/app/<id> right away, even before anyone signs in. That link never changes and always works, so an agent can keep using it as a stable reference.

Sign in and claim it, and it gets a short link. Once you claim an app under a signed-in account, it also gets a friendly URL: charm.ing/<handle>/<app-name>, your handle followed by the app’s own short name. This is the link worth sharing.

You already have a handle. Signing up gives you a handle automatically, something like spinning-otter-4821. To change it, open the account menu, choose Account settings, then Profile. You can also ask your agent.

An app’s name starts from its title, then stands on its own. When an app is created, Charming turns its title into a URL-safe name (Weather Dashboard becomes weather-dashboard). After that, the two are independent: editing the title later never changes the URL, and renaming the URL never changes the title. To rename an app’s URL, find the app on Account Home and choose App settings. You can also ask your agent.

Old links keep working. Change your handle or an app’s name and the old URL keeps opening the app: it redirects to the new one, so a link you already shared never breaks.

Technical

An app’s URL slug and a user’s handle are both assigned automatically and can both be changed without an agent. Use the app’s App settings page for its name. For your handle, open the account menu, choose Account settings, then Profile. An agent can instead call rename_app or set_handle.

Copy this prompt for your agent

Give my Charming app a cleaner URL and check my handle. Read
https://charm.ing/docs/capabilities/app-names-and-urls.md first.
Suggest a short, URL-safe name based on what the app does, then ask
me to confirm before renaming it or changing my handle.

How an agent performs this job

Use rename_app to change an app name and set_handle to change the signed-in user’s handle. Both tool pages define their inputs, rules, and errors.

Host customization API

The signed-in Host UI uses generated first-party API contracts for App customization. Each route requires app:manage and returns the standard { ok: true, ... } or { ok: false, error } envelope.

Use the generated Query options from @buildy/api-client/queries in Charming UI code. The matching exports are checkAppNameAvailabilityOptions, renameAppNameMutation, updateAppIconMutation, and updateAppStarterPromptMutation.

The contract

rename_app is owner-only. set_handle acts on the signed-in user. See Authentication when a caller has no user token.

Tool results that reference an app carry two different links: shareUrl is the one to give the user, the friendly /<handle>/<app-name> form when one exists, never carrying a token. url is the machine /app/<id> form, and it often embeds a write-capable access token. Never show, paste, or send it to the user.

Limits, access, and deletion

• Uniqueness scope. A handle is unique across every account on Charming. An app’s name only has to be unique among your own apps, so you and someone else can each own an app named weather under your own handles.
• Rules and rate limits. See set_handle, rename_app, and Limits.
• The machine URL never changes. charm.ing/app/<id> keeps working forever, including for an app nobody has claimed yet, so an agent that stored that link never needs to update it.

Related

• Privacy and sharing
• How Charming works
• Docs home
• llms-full.txt