Start on your computer
Start GroundControl from your computer
Choose this computer or an existing Linux server. The launcher prepares the instance and prints a private link for setup or login.
A private GroundControl workspace, your owner account and a clear next step for your first project.
On this page
Choose where it runs
| Destination | What you need |
|---|---|
| This computer | macOS or Linux with Docker Desktop / Docker Engine running Linux containers. Windows uses a WSL terminal with Docker integration. |
| Remote Linux server | An AMD64 Linux server and OpenSSH access from your computer. Use your existing SSH alias or user@host; the account needs root or passwordless sudo. |
| Apple Silicon | The published image currently uses AMD64 emulation in Docker Desktop. A native ARM image is not yet provided. |
Local GroundControl manages Docker workloads. It does not manage native Mac or Windows services. On a server, GroundControl is a privileged host operations tool; install it on infrastructure you intend it to manage.
1. Run the launcher on your computer
curl -fsSL https://raw.githubusercontent.com/teckedd-code2save/groundcontrol/main/scripts/start -o groundcontrol-start
bash groundcontrol-startChoose this computer or a remote server when prompted. Local setup uses Docker. Remote setup connects through SSH, installs GroundControl on the server and opens the private tunnel for you.
You can also choose the destination directly:
bash groundcontrol-start --localbash groundcontrol-start --remote your-user@your-serverThe launcher prints a link on 127.0.0.1. A new instance opens setup; an instance you already own opens login. Local setup writes its configuration to .groundcontrol-desktop in the current folder by default. Retain that folder and the Docker database volume.
2. Open your private setup link
Open the complete link printed by the launcher in your browser on the same computer. Its one-time claim token establishes ownership; keep the link private.
| Installation | While you use GroundControl |
|---|---|
| Local | Keep Docker running. You can close the launcher after setup finishes. |
| Remote | Leave the launcher terminal open: it carries your SSH tunnel. Run the same launcher command again to reconnect later. |
The remote server stays private unless you deliberately publish it. Rerunning the launcher reconnects to an existing installation; it does not upgrade it.
3. Create your owner account
On Claim GroundControl, enter an administrator username and a password with at least 12 characters, upper and lower case letters, a number and a symbol. This account belongs to your own instance.
A claim link is single-use and expires after 30 minutes by default. Rerun the launcher for a fresh link if the unclaimed instance’s link expires. An already-claimed instance uses your existing login.
The local Docker workspace or destination Linux host is connected automatically. Continue setup to review it; you do not need to add that same host a second time.
4. Verify and add your first project
Use the private verification step, then review the onboarding summary. On a desktop, the Linux environment belongs to the container; it is not the operating system of your Mac or Windows PC.
Open Projects → Add project. Pick a folder or a GitHub repository, then connect an existing deployment or launch a new one. Follow the projects and deployments guide.
A local-only address is for you on this computer. Remote MCP clients need a reachable HTTPS endpoint. The server installation supports publishing over HTTPS; desktop onboarding stays private.
Advanced: install directly on a Linux server
If you are already working in the destination server’s shell, use the canonical installer. Unlike the computer launcher, this command does not open an SSH tunnel on your computer.
curl -fsSL https://raw.githubusercontent.com/teckedd-code2save/groundcontrol/main/scripts/install | sudo bashAdd -s -- --json after bash for structured installer output. From your computer, forward the default management port with:
ssh -N -L 3003:127.0.0.1:3003 your-user@your-serverOpen the server installer’s complete claim link through that tunnel. Server installations live under /opt/groundcontrol by default and use persistent Docker database storage. See upgrade and recovery for maintenance.