Custom share URL name (custom slug + short link)
Paid accounts can give a share link a memorable name instead of a random token, so it reads as a word rather than a 64-character string, and can opt into a short link on top. Covers who is eligible, the naming rules, what happens when a name is taken or re-used, and how the in-app viewer resolves either kind of link.
On this page
What it is
Paid users (Pro or above) can replace the random 64-hex token in a share link with a memorable name, so the public page reads https://shares.omniscio.com/s/<name> instead of https://shares.omniscio.com/s/<token>. An optional short link (omnisc.io/<code>) can be minted for the same share at publish time.
This applies to any share that goes through the standard publish pipeline — session / message shares (artifact-sharing.md), file and pasted-content artifacts (share-artifacts.md), and CLI publishes (share-cli.md). The feature is toggled by the customShareUrlEnabled setting (Settings → Sharing), default off.
Where to find it
Both controls are on the publishing path rather than in a page of their own. The public name is offered in the share publish dialog, where you type the name you want; the switch that turns the whole feature on is Settings → Sharing. The agent-facing short-link default has its own switch in the same settings section, under the wording about defaulting to short share links.
How it behaves
Custom slug (the /s/<name> link)
- Eligibility. Every plan can set a custom name (no feature is Pro-only). The relay checks only that you own the share, that nobody else holds the name, and that your account holds fewer than 200 names.
- How it's set. The publish payload accepts a
customSlugfield (1–80 chars). After the share is uploaded, the slug is claimed through the share relay'sclaim-slugop. If the name is already taken the claim fails gracefully and the publish falls back to the token URL — publishing is never blocked by a name collision. - Re-using your own name (re-publish). Publishing new content under a name you already own moves the name to the newest share: the relay re-points it globally and the local record transfers it in one atomic step (
setShareSlugreleases the name off the prior live share before setting it on the new one), so/s/<name>always resolves to your latest publish. The older share is taken down at the same moment — the relay revokes it, so its token URL answers "no longer available" rather than still serving the page you replaced, and the app marks that share revoked. This holds for a re-publish or two near-simultaneous publishes of the same name — it never fails with aUNIQUE constraint failed: shared_links.slugerror. - Name rules (
share-slug-rules.ts, the single source of truth, mirrored byte-for-byte in the relay):- 4–80 characters; lowercase alphanumerics plus interior hyphens; must start and end alphanumeric (no leading/trailing hyphen).
- A name shaped like a 16- or 64-hex share token is rejected — the share router's hex fast-path resolves tokens first, so such a slug would be unreachable.
- Structural route words are reserved and always blocked:
s,run,video,unlock,png,inner. - A small anti-squatting denylist (
demo,home,apps,pricing,login,admin,support, …) stops any single user from locking away generic or premium words globally. - The publish UI pre-validates a name against these rules before the round-trip, showing the same message the relay would; the relay remains the authoritative validator.
- One account holds at most 200 chosen names. The cap exists to stop one paid month registering thousands of brand-looking names; re-pointing or renaming a name you already hold costs no new slot. A machine-minted short link never counts toward it — codes live in their own lane, so an account with thousands of shared links can still choose a name (fixed 2026-10-20: the cap used to count every code, which silently stopped short links for any busy account). Every name you type counts, whatever it looks like: a readable word that happens to look like a short code (
payments,checkers) is a chosen name, because only the share server itself can mint a short code (F027, fixed 2026-11-07 at the owner's request ahead of launch). Short links already in use keep working and still do not count. A refusal reads "You already hold the maximum of 200 custom link names" and means the 200 chosen-name slots are genuinely full. - If a name is refused. A taken name says so and the publish keeps the random token URL; a name already held by someone else can never be taken over. Nothing about a refusal blocks the share itself.
Short link (the omnisc.io/<code> opt-in)
- System-minted. At publish time (when no custom slug is set and the short-link opt-in is on), the share server mints the code itself (the
mint-short-codeop), from an unambiguous 31-symbol alphabet that omits0,1,i,l,oso a link read aloud or hand-typed can't be mis-keyed, and marks it as a system code. The desktop falls back to generating a code and claiming it throughclaim-slugonly while the server it talks to has not yet been updated with that op.- Length is the publisher's choice (2026-10-23). A
Selectunder the short-link checkbox picks Standard — 13 characters (the default) or Short — 8 characters, like a bit.ly link. Standard carries ~64 bits and meets the entropy floor on its own; Short carries ~40 bits and is safe only because of the gateway cap described next. A code minted at any earlier length keeps working — a republish reuses the code saved on the share's own row. - Why the length matters at all. A short code resolves through the same serving path as the share's 256-bit token, so for a share with no password the code is the capability, and one global keyspace is shared by every user's short links. The original 7 characters (~35 bits) left a scanner about 2.7M requests from someone else's unlisted share at 10k short-linked shares.
- Length is the publisher's choice (2026-10-23). A
- Wrong guesses are capped per network (2026-10-23). A share name that is not a hex token is a name, and name lookups that miss are limited to 30 per 15 minutes per network — bucketed at /24 for IPv4 and /48 for IPv6 (
share-lookup-throttle.ts). Past that the gateway answers 429 with aRetry-Afterto every named lookup from that network, real links included: answering a real link normally would hand a scanner its yes/no at full speed and make the cap decorative. The collateral is that one scanner can get its entire /24 or /48 refused for the 15-minute window — that is the price of a cap that leaks nothing. The cap is fail-open: a counter-store fault allows the lookup, and a deploy with no IP salt stands the cap down rather than putting every caller in one bucket. - Collision-safe. A rare collision is retried by regenerating (up to 3 attempts); only a genuinely "taken" code is worth retrying. Any other failure (not paid / invalid / error) leaves the share with its token URL.
- Never fatal. A short link is optional: every failure path degrades to "keep the token URL" rather than breaking the publish.
- Stable across republishes (fixed 2026-08-29). A share keeps the SAME short code every time it is republished — the publish REUSES the code already saved on the row instead of minting a new one. This fixes a bug where each republish minted a FRESH code whose claim released the previous one, so every short link handed out earlier began 404ing and only the newest worked. Re-claiming the same code for the same share is idempotent server-side, so a republish also revives the current link if an earlier one had already broken it. Codes overwritten before this fix are not locally recoverable and are not revived.
- A custom name wins over a short link. A share has ONE pretty-URL slot (a short code and a custom name are both claimed there), so when the share already carries a custom name the short-link request is REFUSED — the publish returns a
shortLinkErrorsaying so — rather than silently replacing the name. To switch a share to a short link, clear its custom name first. - Persisted + opens in-app (2026-08-19). A claimed code is saved on the local share row (
short_code), so a receivedomnisc.io/<code>link opens in the in-app floating viewer — on the canonicalshares.omniscio.com/s/<code>page, neveromnisc.io— and is background-warmed for an instant open, exactly like a full/s/<token>link. Short links minted before this column still open in-app but aren't inbox-preloaded or shown with the owner's label (their code wasn't saved and isn't locally recoverable).
Behaviour with in-app shares
When sharesOpenInApp is on, a share link opens in the in-app floating viewer instead of the browser. The viewer builds the canonical shares.omniscio.com/s/<…> URL from the link's validated token OR short code — never the raw href, and never omnisc.io (a redirect alias that is deliberately never loaded in the webview). The custom slug / short-link variants resolve through the same serveShare path — a slug or short code is just a claimable alias into the one share-index, not a parallel system. A short link is also background-warmed (and inbox-preloaded when it is your own share), so it opens instantly like a long /s/<token> link.
The paid-plan lock is visible, not invisible
- A locked field, never a missing one. The publish dialog shows the custom-name field whenever
the
custom-share-urlfeature flag is on. A user below the required tier gets it disabled, with a plan badge (minTierLabel('custom_share_url'), e.g. "Pro+") and a "See plans" link that opens Settings → Plan & Usage. Before this, the field simply did not render for a Free user — no lock, no badge, no tooltip — which is indistinguishable from a bug, and nothing in the dialog said the feature was paid. - The gate still holds underneath.
customSlugandshortLinkare stripped from the publish payload whenever the entitlement is absent, so the visible control is UX only; the relay remains the authority.
Related
Which kinds of share go through the pipeline this page describes — session and message shares, file and pasted-content artifacts, and agent publishes over the command line — is on the artifact sharing, share artifacts and share CLI pages respectively. If a link of yours is not opening where you expect, the shares view covers the in-app list and viewer that a received link is resolved into.
Last verified 2026-11-08