Local Deployment

ServOS is designed to manage remote servers, but you can also use it to deploy services directly to your local machine (e.g., your MacBook or Linux workstation). This is useful for development, testing, or running lighter loads without paying for a cloud VPS.

Prerequisites

Before connecting your local machine, ensure you have the following installed:

1. Docker Engine (or Docker Desktop/OrbStack on macOS).
2. SSH Server enabled and running.

0. Running ServOS Internally (Dev Mode)

If you are developing ServOS itself or running the control plane locally without root permissions:

1. Set Data Directory: Use SERVOS_DATA_DIR to point to a local writable folder.
2. Generate Token: Use the CLI to create the initial setup token.

# 1. Prepare data directory
mkdir -p servos-data

# 2. Generate Setup Token
SERVOS_DATA_DIR=$(pwd)/servos-data cargo run --bin servos-api -- reset-setup-token

# 3. Running Control Plane
SERVOS_DATA_DIR=$(pwd)/servos-data cargo run --bin servos-api

Then visit http://localhost:3000/setup and use the token generated in step 2.

1. Enable SSH Access

ServOS connects to all servers—including your local machine—via SSH.

on macOS

1. Open System Settings.
2. Go to General > Sharing.
3. Toggle Remote Login to ON.
4. Click the “i” info button and ensure your user is allowed access.
5. Note the command shown (e.g., ssh [email protected]) to verify it works.

on Linux (Ubuntu/Debian)

Install and start the OpenSSH server:

sudo apt update
sudo apt install openssh-server
sudo systemctl enable --now ssh

2. Verify Docker Permissions

The SSH user you connect with must have permission to run docker commands without sudo.

on macOS (Docker Desktop / OrbStack)

This typically works out of the box for the logged-in user. You can verify by running:

ssh localhost docker info

If you see Docker details, you are good to go. If you get command not found, you may need to add Docker to the system PATH for non-interactive shells.

on Linux

Add your user to the docker group:

sudo usermod -aG docker $USER
newgrp docker

Verify via SSH:

ssh localhost docker info

3. Add Server to ServOS

1. Log in to your ServOS dashboard.

2. Go to the Servers tab.

3. Click Add Server.

4. Fill in the details:

   • Name: Localhost (or My MacBook)
   • IP Address: 127.0.0.1 (or your LAN IP if running ServOS in a container that can’t see host localhost)
   • User: Your system username (run whoami to check)
   • Authentication:
     • SSH Key: Paste the contents of your private key (e.g., cat ~/.ssh/id_ed25519).
     • Password: Alternatively, use your user login password.

5. Click Create Server.

Troubleshooting Connection

If ServOS cannot connect to 127.0.0.1, it might be because ServOS itself is running inside a Docker container. In that case, 127.0.0.1 refers to the container, not your machine.

• If ServOS is running via npm run dev (host process): Use 127.0.0.1.
• If ServOS is running via Docker: Use host.docker.internal (if supported) or your machine’s LAN IP (e.g., 192.168.1.x).

4. Commission & Deploy

Once added, click Commission on the server detail page. ServOS will:

1. Connect via SSH.
2. Install the hardened servos-agent as a background service.
3. Configure WireGuard mesh networking.
4. Install the Traefik proxy/load balancer.

Once commissioned (Status: Ready), you can create specific services and deploy them to your new “Localhost” server!