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. Change it to something that’s actually you from charm.ing/account/handle or by asking 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. Rename an app’s URL from its settings page on your dashboard or by asking 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 overridden: the dashboard app settings page and charm.ing/account/handle change them without touching your agent, or your agent calls rename_app and 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

Your agent renames an app’s URL with rename_app, passing the app id and the new app_name. It changes the signed-in user’s handle with set_handle, passing only the new handle. The tool always acts on whoever is currently signed in, never a user id an agent supplies. Neither call is required to create or update an app: a slug is derived from the app’s title (falling back to its manifest id, then a random app-<id> form) the first time create_app runs, and a handle is assigned the moment an account is created. An agent only calls these tools to override the auto-assigned value. Both changes take effect immediately, and the app’s previous URL starts redirecting to the new one in the same moment.

The contract

rename_app({ app_id, app_name }); // app_name: 2-48 chars, lowercase letters/digits/hyphens, may start with a letter or digit
set_handle({ handle }); // handle: 3-32 chars, lowercase letters/digits/hyphens, must start with a letter

rename_app is owner-only: a collaborator can open and edit an app’s code but can’t change its URL. set_handle needs no id. It fails with an unauthenticated error for a connection with no signed-in user (anonymous, render-token, or test connections); sign in first to get a handle to change.

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

Handle rules. Lowercase letters, digits, and hyphens; 3-32 characters; must start with a letter; no leading, trailing, or consecutive hyphens; some words are reserved.
App name rules. Lowercase letters, digits, and hyphens; 2-48 characters; may start with a letter or a digit, so an app can be named 100-pushups; no leading, trailing, or consecutive hyphens; some words are reserved.
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.
Handle changes are rate-limited. At most 3 handle changes in a rolling 30 days. Renaming an app’s URL has no such limit.
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.
Failed rename. A rejected rename_app call returns an error.kind naming the reason: taken, reserved, unchanged, too_short, too_long, bad_chars, leading_hyphen, trailing_hyphen, consecutive_hyphens, or not_found. The recovery is to pick a different name and retry.
Failed handle change. A rejected set_handle call returns an error.kind naming the reason: taken, reserved, unchanged, too_short, too_long, bad_chars, bad_start, trailing_hyphen, consecutive_hyphens, or rate_limited. The recovery is to pick a different handle and retry, except rate_limited, where the recovery is to wait.