Skip to main content
Star zrok on GitHub Star
Version: 2.0 (Current)

Manage reserved names

Reserved names give your shares a persistent, human-readable identifier that survives across share sessions. Namespaces are the containers that organize names. This how-to covers the full lifecycle: creating names, using them with shares, managing them, and configuring a default namespace.

Create a reserved name​

Use zrok2 create name to reserve a name in a namespace:

zrok2 create name myapp

To create a name in a specific namespace, use the -n flag:

zrok2 create name -n public myapp

To create a name in a custom namespace:

zrok2 create name -n <namespaceToken> api

Once created, the name persists even when your share isn't running and can be reused across share sessions.

Use names with shares​

Public shares​

Use the -n flag to attach a name to a public share:

zrok2 share public localhost:8080 -n public:myapp

To use a name in a specific namespace:

zrok2 share public localhost:8080 -n <namespaceToken>:api

The name can be either reserved (created with zrok2 create name) or ephemeral (created on-the-fly when the share starts). See Reserved names and namespaces for a full explanation of the difference.

Private shares with custom tokens​

For private shares, use the --share-token flag to specify a persistent vanity token:

zrok2 share private localhost:8080 --share-token myapi-prod

Access it from another environment:

zrok2 access private myapi-prod

zrok2 share private --share-token terminal output

When using the zrok agent, shares with --share-token automatically restart after abnormal exit or agent restart. See zrok agent overview for more details.

Multiple names on one share​

You can specify multiple names for a single share:

zrok2 create name -n public myapp
zrok2 create name -n public myapp-staging
zrok2 share public localhost:3000 \
  -n public:myapp \
  -n public:myapp-staging

Both URLs point to the same backend target, letting you use different names for the same service.

Manage names​

List your names​

See all your names across all namespaces:

zrok2 list names

This shows a table with:

  • URL (the full public URL if applicable)
  • Name
  • Namespace
  • Share token (if being shared)
  • Reserved status
  • Creation timestamp

Modify name status​

Toggle the reserved status of a name:

zrok2 modify name -n public myapp -r

To make a name ephemeral (deleted when the share ends):

zrok2 modify name -n public myapp -r=false

Delete a name​

Remove a name when you no longer need it:

zrok2 delete name myapp

To delete a name from a specific namespace:

zrok2 delete name -n <namespaceToken> api

Configure a default namespace​

Set a default namespace to avoid specifying -n on every command:

zrok2 config set defaultNamespace public

Or set it via environment variable:

export ZROK2_DEFAULT_NAMESPACE=public

Once configured, commands use this namespace by default. These two commands become equivalent:

zrok2 create name myapp
zrok2 create name -n public myapp