Getting Started

Your First Connection

Connect CtrlOps to your first Linux server using SSH keys, a password, or a pasted connection string. Step-by-step setup, no command line needed.

Welcome to CtrlOps! Adding your first server connection is the gateway to streamlining your DevOps workflow. This guide walks you through the exact steps to securely connect your machine to your server.

Prerequisites: SSH Setup Wizard

Before adding a connection, your local machine needs to be properly configured for SSH. If you haven't done this before, CtrlOps includes a built-in SSH Setup Wizard to make the process effortless.

To access the wizard:

Click the New Connection button on your dashboard.
At the top of the modal, look for the blue "Need help with SSH setup?" alert.
Click Open SSH Setup.

The wizard will guide you through three critical steps:

SSH Installation: Verifies that the OpenSSH client is installed on your OS.
SSH Keys: Checks for existing keys or helps you generate a secure new key (Ed25519 recommended).
Server Setup: Provides exact commands (like ssh-copy-id) to securely copy your public key to your target server.

Already have SSH keys set up? You can skip the wizard and proceed directly to adding your connection! And if you also keep a hand-written ~/.ssh/config for terminal use, our free SSH config generator writes clean host blocks you can paste straight in.

What You Need

Before proceeding, ensure you have the following details from your hosting provider (AWS, DigitalOcean, Hetzner, etc.):

IP Address - Your server's public IP (e.g., 203.0.113.0).
Port - The SSH port. It defaults to 22; you only need this if your server listens on a non-standard port.
Username - Usually root, ubuntu, ec2-user, or your custom admin account.
Authentication - Either your configured SSH key, a .pem file, or a password.

Already have a working SSH command? You don't have to fill anything in by hand. Paste your full connection string into Quick Connect at the top of the form and CtrlOps fills the details for you, see the next section.

Connecting Step-by-Step

Start a New Connection

From the CtrlOps dashboard, click the New Connection button in the top right corner (or Add First Connection if your dashboard is empty).

Quick Connect with a connection string (fastest)

At the top of the form is the Quick Connect via SSH String (Optional) field. If you already have a working SSH command, paste it here and CtrlOps parses it to auto-fill the IP Address, Username, Port, and key path for you. It works on both authentication tabs.

Both common formats are recognized:

# Full ssh command with a key file and custom port
ssh -i ~/.ssh/mykey.pem user@192.168.1.1 -p 2222

# Simple user@host (great for AWS EC2 endpoints)
ubuntu@ec2-65-0-241-41.ap-south-1.compute.amazonaws.com

Once the fields populate, you can connect straight away or adjust anything before saving. Prefer to enter details by hand? Skip this field and use the next step instead.

Fill in Server Details

Server Name (optional): Give your connection a friendly, recognizable name (e.g., "Production Database").
IP Address: Paste your server's public IP address or hostname.
Port: The SSH port, pre-filled with 22. Change it only if your server listens on a non-standard port.
Username: Enter the exact SSH username.

Choose Authentication Method

Select the tab that matches your security setup:

By default, CtrlOps uses your system's standard SSH keys (like ~/.ssh/id_ed25519).

Using a password instead? Toggle the Use password authentication switch, enter your password, and optionally check Remember password for automatic future connections.

Passwords are convenient but less secure than SSH keys. We highly recommend using the SSH Setup Wizard to transition to key-based authentication.

Perfect for AWS EC2 or other cloud providers that give you a downloaded key file.

Click Select .pem Key File to browse your computer, or manually paste the absolute path to your .pem or .key file.

Connect through a proxy or bastion (optional)

If your server isn't reachable directly and you have to hop through a jump host, expand Advanced Settings and fill in the Proxy Command (Optional) field. CtrlOps routes the connection through the host you specify.

ssh -W %h:%p user@bastion

Leave this empty for servers you can reach directly.

Connect and Automate

Click Connect SSH (or Connect with .pem).

CtrlOps will automatically perform a pre-flight test to verify your credentials. Once successful, the connection is saved, and you will be immediately routed to your new instance dashboard!

Connection Troubleshooting

If the connection fails, CtrlOps will display a specific error. Here is how to resolve the most common issues:

"Authentication failed" / "Permission Denied"

Double-check your username (it is case-sensitive).
If using a password, ensure it is typed correctly.
If using a .pem file, ensure it has the correct permissions (chmod 400 key.pem).
If using standard SSH keys, ensure your public key was properly added to the server's ~/.ssh/authorized_keys file.

"Cannot reach server" / "Connection Timed Out"

Verify the IP address is correct.
Check that the server is currently powered on in your cloud provider's dashboard.
Ensure port 22 (SSH) is open in your server's firewall/security groups.

"Connection Refused"

The server is online, but the SSH service is not running or is configured to use a non-standard port. If it uses a different port, set the Port field to match.
If the server is only reachable through a jump host, add the bastion to the Proxy Command field under Advanced Settings.

Windows: SSH Agent Not Running

If you are using standard SSH keys on Windows and connections fail, your Windows SSH Agent service might be stopped.

Run these commands in PowerShell (as Administrator):

Set the service to start automatically:

Set-Service -Name ssh-agent -StartupType Automatic

Start the service now:
```
Start-Service ssh-agent
```
Add your private key (replace id_ed25519 with your filename if different):
```
ssh-add $env:USERPROFILE\.ssh\id_ed25519
```

Restart CtrlOps and try connecting again.

Next Steps

Now that you're connected to your server, explore what CtrlOps can do:

Need Help?

Can't find your answer in the docs? We're here to help you get unstuck.

Email Support: support@ctrlops.io
Feature Requests: Reach out if you have an idea that would make CtrlOps better!
Need more help?: Join our Discord community

Download & Install

Download CtrlOps for macOS, Windows, or Linux. The native desktop app installs in minutes and manage your servers without the command line.

AI SSH Terminal

CtrlOps AI SSH Terminal is a full Linux terminal with a built-in AI terminal assistant. Ask questions in plain English, get the right Linux commands, review before execution, and let AI explain every output. It turns natural language into bash - instantly.

Join the communityDiscord community Need help? Email ussupport@ctrlops.io

On this page

Prerequisites: SSH Setup Wizard What You Need Connecting Step-by-Step Start a New Connection Quick Connect with a connection string (fastest)Fill in Server Details Choose Authentication Method Connect through a proxy or bastion (optional)Connect and Automate Connection Troubleshooting "Authentication failed" / "Permission Denied""Cannot reach server" / "Connection Timed Out""Connection Refused"Windows: SSH Agent Not Running Next Steps Need Help?