Connect an existing VPS

This path creates a local profile, prepares its Git-backed configuration, and runs bootstrap, hardening, networking, proxy, and observability as one reviewed plan.

Before you begin

You need a supported fresh VPS, working SSH key, domain, and DNS access. Build Servestead and run ./bin/servestead doctor first.

1. Start a profile

./bin/servestead setup

Choose Set up a new server profile.

2. Enter required values

Complete the setup intake:

Field	What to enter
Server address	The fresh server’s public IP address or hostname.
Private key	A path on this machine, such as ~/.ssh/servestead_ed25519.
Base domain	The domain Servestead will use for Pangolin and application routes.
Let’s Encrypt email	The certificate contact address.

The profile name is optional and defaults to the server address. Press ctrl+a only when you want to set a recognizable name or change the initial user, administrative user, Pangolin administrator, or other advanced values.

3. Choose the configuration repository

Pick one repository mode:

• Create local repository uses the profile’s default configuration location.
• Use existing local checkout uses a repository you already own.
• Clone GitHub repository clones an HTTPS URL. Add a PAT only for a private repository or to avoid anonymous rate limits.

Servestead deploys committed configuration. It does not prepare the repository before you approve the plan.

4. Review the plan

Verify the server address, users, domain, repository action, and planned stages. No SSH command has run yet.

Press r only when the plan matches your intent. Servestead runs local preflight and repository preparation before it opens the SSH connection.

5. Follow the run

The run view shows status, progress, the current task, and live logs. ctrl+c requests cancellation and keeps the cancelling state visible until the active operation stops. If SSH work has begun, the active remote task may already be partially applied; inspect the saved run and remote state before retrying. A later run keeps completed stages and can skip them.

Expected result

The profile dashboard shows Bootstrap, Harden, and Platform complete. Press h to inspect the saved run and its redacted log. If a stage failed, start with the reported stage and task in Common issues.

Start directly from an address

./bin/servestead setup --ip 203.0.113.10

Use --fresh only when you intentionally want a new local profile for a reused address. Servestead preserves the prior profile instead of overwriting it.