---
title: App names and URLs
description: "Every app gets a short, shareable URL built from your handle and the app's own name, and both are yours to change."
sidebar:
  label: App names and URLs
  order: 4
---

## 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](https://charm.ing/) 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

```text
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`](/docs/technical-reference/mcp/tools/rename_app) to change an app name and [`set_handle`](/docs/technical-reference/mcp/tools/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.

| Method  | Route                                                   | Change                                  |
| ------- | ------------------------------------------------------- | --------------------------------------- |
| `GET`   | `/api/v1/apps/{appId}/name-availability?appName={name}` | Check a URL name before rename.         |
| `PATCH` | `/api/v1/apps/{appId}/name`                             | Rename and retain the old name alias.   |
| `PATCH` | `/api/v1/apps/{appId}/icon`                             | Set the emoji and background color.     |
| `PATCH` | `/api/v1/apps/{appId}/starter-prompt`                   | Set or clear the agent starter prompt.  |

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](/docs/technical-reference/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`](/docs/technical-reference/mcp/tools/set_handle), [`rename_app`](/docs/technical-reference/mcp/tools/rename_app), and [Limits](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](privacy-and-sharing)
- [How Charming works](../concepts/how-charming-works)
- [Docs home](..)
- [llms-full.txt](https://charm.ing/docs/llms-full.txt)

Found a bug or need a feature? [Tell us](/docs/capabilities/feedback) with `submit_feedback` or `POST /app/{id}/feedback`. Your feedback shapes what we build next.