Local Deployment

ACT 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 ACT Internally (Dev Mode)

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

1. Set Data Directory: Use ACT_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 act-data

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

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

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

1. Enable SSH Access

ACT 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 ACT

1. Log in to your ACT 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 ACT 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 ACT cannot connect to 127.0.0.1, it might be because ACT itself is running inside a Docker container. In that case, 127.0.0.1 refers to the container, not your machine.

• If ACT is running via npm run dev (host process): Use 127.0.0.1.
• If ACT 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. ACT will:

1. Connect via SSH.
2. Install the hardened act-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!