Skip to main content

​
Overview

suSHi allows you to centrally manage all your SSH machines in one place. Store connection details securely, organize machines by purpose, and connect with a single click.

​
Machine Properties

Each machine in suSHi stores the following information:
Required fields:
  • Name: Friendly identifier for the machine (e.g., “Production Server”)
  • Hostname: IP address or domain name (e.g., 192.168.1.100 or server.example.com)
  • Port: SSH port number (typically 22)
  • Username: SSH login username
All sensitive data (private keys, passphrases, passwords) is encrypted using AES-256-CFB before storage. See Security for details.

​
Adding a Machine

​
Via Dashboard

1

Navigate to Machines

Click on Machines in the main navigation menu
2

Click Add Machine

Click the Add New Machine button in the top right
3

Fill Basic Details

Enter the machine’s name, hostname, port, and username
4

Configure Authentication

Choose between private key or password authentication:
  • For private key: Paste your private key content
  • For password: This will be requested during connection
Private keys are stored encrypted. Passwords are requested at connection time for maximum security.
5

Add Organization (Optional)

Group the machine under an organization for better organization
6

Save Machine

Click Save to add the machine to your workspace

​
API Request

You can also add machines programmatically: 
curl -X POST https://your-domain.com/api/machines \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Server",
    "hostname": "192.168.1.100",
    "port": "22",
    "username": "admin",
    "private_key": "-----BEGIN RSA PRIVATE KEY-----\n...",
    "passphrase": "key-passphrase",
    "organization": "Production"
  }'

{
  "status": 200,
  "message": "Machine created successfully",
  "data": null
}

​
Viewing Machines

​
Machine List

The machine dashboard shows all your machines with:
  • Machine name and hostname
  • Username and port
  • Organization (if set)
  • Quick action buttons (Connect, Edit, Delete)
Only basic information is displayed in the list view. Sensitive credentials are never shown in the UI.

​
Machine Details

Click on any machine to view detailed information: 
// Example machine object returned by API
{
  "id": 1,
  "name": "Production Server",
  "hostname": "192.168.1.100",
  "port": "22",
  "username": "admin",
  "owner_id": "[email protected]",
  "owner_type": "user",
  // Sensitive fields (private_key, passphrase) are excluded
}
Organize your machines:
  • Search by name: Find machines quickly
  • Filter by organization: View machines by team or project
  • Sort by date: See recently added or modified machines

​
Connecting to Machines

To establish an SSH session:
1

Select Machine

Find the machine you want to connect to in your dashboard
2

Click Connect

Click the Connect button on the machine card
3

Enter Encryption Password

Provide your master password to decrypt stored credentials:
{
  "password": "your-master-password"
}
4

Connection Established

Server decrypts credentials and establishes SSH connection
5

Terminal Opens

You’re redirected to the web terminal with active SSH session

​
Connection Flow

The connection process uses your master password to decrypt stored credentials, then establishes a fresh SSH connection to the machine.

​
Deleting Machines

Deletion is permanent! This action cannot be undone. All stored credentials for the machine will be permanently deleted.

​
Delete via Dashboard

  1. Find the machine in your list
  2. Click the Delete button (trash icon)
  3. Confirm deletion when prompted

​
Delete via API

curl -X DELETE https://your-domain.com/api/machines/:id \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
Response: 
{
  "status": 200,
  "message": "Machine deleted successfully",
  "data": null
}

​
Security Considerations

Credential Encryption

All private keys and passphrases are encrypted with AES-256-CFB using PBKDF2 key derivation.

Password Protection

Your master password is never stored. It’s required to decrypt credentials at connection time.

User Isolation

You can only access machines you own. JWT authentication ensures proper authorization.

Audit Trail

All machine operations (create, connect, delete) are logged for security auditing.

​
Machine Ownership

Machines are owned by users or organizations: 
// Machine ownership model
type FilterMachine struct {
    ID         int    `json:"id"`
    Name       string `json:"name"`
    Username   string `json:"username"`
    Hostname   string `json:"hostname"`
    Port       string `json:"port"`
    OwnerID    string `json:"owner_id"`    // User email or org ID
    OwnerType  string `json:"owner_type"`  // "user" or "organization"
}
Owner Types:
  • user: Personal machines (default)
  • organization: Shared team machines (future feature)
Currently, all machines are user-owned. Organization-level sharing is planned for future releases.

​
API Reference

​
Create Machine

Endpoint: POST /api/machines Request Body: 
{
  "name": "string",
  "hostname": "string",
  "port": "string",
  "username": "string",
  "private_key": "string",     // Optional
  "passphrase": "string",      // Optional
  "password": "string",        // Optional
  "organization": "string"     // Optional
}

​
Get All Machines

Endpoint: GET /api/machines Response: 
{
  "status": 200,
  "message": "Machines fetched successfully",
  "data": [
    {
      "id": 1,
      "name": "Production Server",
      "hostname": "192.168.1.100",
      "port": "22",
      "username": "admin",
      "owner_id": "[email protected]",
      "owner_type": "user"
    }
  ]
}

​
Get Single Machine

Endpoint: GET /api/machines/:id Response: Same as individual machine object above

​
Connect to Machine

Endpoint: POST /api/machines/:id/connect Request Body: 
{
  "password": "your-master-password"
}
Response: 
{
  "status": 200,
  "message": "Connected to machine successfully",
  "data": "550e8400-e29b-41d4-a716-446655440000"  // Session UUID
}

​
Delete Machine

Endpoint: DELETE /api/machines/:id Response: 
{
  "status": 200,
  "message": "Machine deleted successfully",
  "data": null
}

​
Best Practices

SSH keys are more secure than passwords and support additional encryption with passphrases.Generate a key pair:
ssh-keygen -t ed25519 -C "[email protected]"
Then copy the private key content to suSHi.
Use descriptive names that help you identify machines quickly:
  • Good: “Production API Server”, “Dev Database”
  • Bad: “Server1”, “Machine2”
Include environment and purpose for clarity.
Use the organization field to group related machines:
  • “Production”
  • “Staging”
  • “Client: Acme Corp”
  • “Personal Projects”
Periodically update SSH keys and passwords:
  1. Generate new credentials on remote machines
  2. Update machine entries in suSHi
  3. Remove old credentials
This limits exposure from compromised credentials.

​
Troubleshooting

Common causes:
  • Incorrect hostname or port
  • Firewall blocking SSH traffic
  • Wrong username or credentials
  • Machine is offline
Solutions:
  1. Verify machine is reachable: ping hostname
  2. Test SSH directly: ssh username@hostname -p port
  3. Check firewall rules on remote machine
  4. Verify credentials are correct
Common causes:
  • Wrong master password for decryption
  • Private key doesn’t match authorized_keys
  • Key passphrase incorrect
Solutions:
  1. Double-check your master password
  2. Verify the private key matches public key on remote
  3. Test key locally: ssh -i private_key username@hostname
  4. Check remote machine’s /var/log/auth.log for details
Cause: Machine ID doesn’t exist or you don’t have permissionSolutions:
  • Verify the machine ID is correct
  • Check that you’re logged in with the right account
  • The machine may have been deleted

​
Next Steps

Web Terminal

Learn how to use the browser-based terminal

Security

Understand how credentials are encrypted and protected

Build docs developers (and LLMs) love

Get started for freeTalk to us