# routeup setup

> One-time install of the local CA, certificates, agent, and optional server credentials.

`routeup setup` prepares your machine for local HTTPS. Run it once after
installing.

```bash
routeup setup
```

Excerpt of the local setup steps on a fresh machine; optional server and token
prompts are omitted:

```txt frame="terminal" title="terminal"
  ✓  certificate authority   created
  ✓  certificate             trusted
  →  port 443                setting up (password required)…
  ✓  port 443                ready
  ✓  agent                   started

  routeup is ready
  try: routeup serve example-app --port 3000
  run routeup --help to see all commands
```

Setup may request one authorization for system trust and privileged-port
changes.

## What it changes

- Creates a local certificate authority under `~/.routeup`.
- Adds that CA to your operating system trust store, so `*.localhost` routes load
  over HTTPS with no browser warnings.
- Lets routeup answer on port 443 (a LaunchDaemon forwarder on macOS, a
  `cap_net_bind_service` capability on Linux).
- Starts the background [local agent](/docs/concepts/local-agent). Later commands
  start it on demand when it is not already running.
- Keeps the local CA private key and saved public-server credentials restricted
  to the current user (`0600`), correcting older permissive modes when used.

It explains each privileged change before making it. Nothing is sent off your
machine, and no account is required.

## Saving server credentials

To configure hosted public exposure at the same time, save the hosted control
endpoint and your token. Granted public URLs still use the `routeup.dev` suffix:

```bash
routeup setup --server https://edge.routeup.dev --token sk_routeup_xxx
```

On an interactive re-run, a saved token is represented by a masked value. Press
Enter at the token prompt to keep it, type `none` to clear only the token, or
enter a replacement token. A saved token is reused only when the selected
server matches the server it was saved for.

The same clearing operations are available through flags:

```bash
routeup setup --token none   # clear the token, keep the saved server
routeup setup --server none  # clear both the saved server and token
```

You can also supply these per command or through `ROUTEUP_SERVER` /
`ROUTEUP_TOKEN`. See [Using a token](/docs/getting-started/using-a-token).

## Re-running

`setup` is idempotent. Running it again repairs missing pieces, for example,
re-applying the Linux capability after a package upgrade, without duplicating
state. [doctor](/docs/cli-reference/doctor) tells you when a re-run is needed.

## Undoing it

[uninstall](/docs/cli-reference/update-uninstall) reverses everything setup did:
it checks live owners, cooperatively stops serve owners, stops the agent, removes
the port-443 forwarder, untrusts the CA, and deletes `~/.routeup`. Active runners
and standalone exposures must be stopped in their owning terminal first.