Skip to content

Last updated: 2025-06-24

Setup ServerSage Bastion (Control Node)

This section provides a step-by-step guide to setting up the ServerSage Bastion on both AWS and non-AWS environments.

Prerequisites

Before deploying the Bastion, ensure the following components are ready:

  • AWS Account: You need an active AWS account to use AWS Systems Manager (SSM).
  • IAM User: Create an IAM user with the necessary permissions to manage SSM and EC2 instances.
  • IAM Role: Create an IAM role that the Bastion will assume to interact with your AWS resources.
  • AWS CLI: Install and configure the AWS CLI on your local machine with the IAM user credentials.

You can follow the AWS IAM Requirements to complete these prerequisites.

Setup ServerSage Bastion

After completing the prerequisites, you should now have an IAM user and role with the necessary permissions to deploy the ServerSage Bastion.

Supported environments include:

  • AWS EC2 instance (preferred)
  • AWS Outposts or on-prem machines registered with AWS Systems Manager

Why EC2? ServerSage is fully integrated with AWS IAM and SSM, making EC2 the most seamless and secure choice for Bastion deployment.

Deploy ServerSage Bastion on AWS Instance

In this setup, the Bastion will run on an AWS-hosted machine. We recommend using an EC2 instance running Ubuntu 20.04 or later.

Security Warning

By default, ServerSage Bastion runs on port 5000.
Exposing this port to the internet is not recommended.
Secure your Bastion using HTTPS and firewall rules.

Step 1: SSH Into Your Server

ssh -i /path/to/your/key.pem ubuntu@your-ec2-public-dns

SSH into your AWS instance. This will be the host that runs the ServerSage Bastion container.

Step 2: Install Docker

Docker is required to run the Bastion. Use the following guide if you haven’t installed it yet

Docker Installation Guide

Makesure Docker is installed and running:

sudo docker --version

ServerSage Bastion runs entirely inside a Docker container.

Step 3: Open Port 5000 (Optional you can change this)

ServerSage Bastion runs on port 5000.
Ensure this port is open in your AWS Security Group.

How to open ports in AWS

🔐 You may still want to restrict this port to internal or VPN-only traffic.

Step 4: Pull the ServerSage Docker Image

Download the latest ServerSage Bastion container:

docker pull serversageai/serversage-bastion:latest

Step 5: Run the Bastion Container

Launch the container with your configuration:

docker run -d \
  -e "PORT=5000" \
  -e "AWS_REGION=ap-xxx-x" \
  -e "AWS_INSTANCE_ID=i-xxx" \
  -e "API_KEY=12345" \
  -e "AWS_ACCESS_KEY_ID=xxx" \
  -e "AWS_SECRET_ACCESS_KEY=xxx" \
  -p 5000:5000 serversageai/serversage-bastion:latest

Environment Variables Explained

Variable Description
PORT Internal port for the Bastion container (default: 5000)
AWS_REGION AWS region of the target instance (e.g., ap-southeast-1)
AWS_INSTANCE_ID EC2 instance ID this Bastion will manage
API_KEY Custom key to protect your Bastion endpoint (can be any unique value)
AWS_ACCESS_KEY_ID IAM user access key
AWS_SECRET_ACCESS_KEY IAM user secret key
-p 5000:5000 Maps container port 5000 to the host; adjust as needed

Step 6. Verify ServerSage Bastion is Running

Run a health check:

curl "http://localhost:5000/ping"
Expected response: 
{"message":"Serversage is up"}

✅ This confirms the Bastion is live and accepting requests.

Step 7: Register the Bastion in ServerSage Dashboard

  1. Log in to your ServerSage dashboard.
  2. Navigate to the Sidebar section.
  3. Choose Add Bastion.
  4. Fill in the required fields:
  5. Bastion Name: A unique name for your Bastion.
  6. Bastion URL: The public URL or IP address of your Bastion (e.g., http://your-ec2-public-dns:5000).
  7. InstanceID: The Instance ID of your EC2 instance (e.g., i-0abcd123456789xyz).
  8. Region: The AWS region where your Bastion is deployed (e.g., ap-southeast-1).
  9. API Key: The API key you set in the Docker run command.
  10. Click Save to register the Bastion.
  11. Your Bastion is now ready to manage AWS resources and run AI-powered instructions.

Deploy ServerSage Bastion on a Non-AWS Instance

In this setup, the Bastion runs on infrastructure outside of AWS.

This could be:

  • A cloud VM (e.g., GCP, Azure, Linode)
  • A local on-premise Linux machine

We recommend using a cloud-based Linux machine (Ubuntu 20.04+) for better network availability and stability.

Setting up ServerSage Bastion on a non-AWS instance requires additional steps to register the instance with AWS Systems Manager (SSM) using a hybrid activation code.

🔐 Important: Your Bastion must still have internet access to communicate with the ServerSage API and any AWS-hosted targets via SSM (if applicable).

What is Hybrid Activation?

Hybrid activation allows you to register non-EC2 machines (e.g., on-prem or other cloud VMs) as managed instances in AWS Systems Manager. AWS Reference

Step 1: Create a Hybrid Activation Code

On configured AWS CLI, run the following command to create a hybrid activation code.

Use the IAM role created earlier on this step Create IAM Role.

aws iam get-role --role-name <role-name>
look for the Arn field in the output:

"Arn": "arn:aws:iam::<account-id>:role/<role-name>"

Step 2: Generate Activation Code

Run the command below from a machine with AWS CLI configured:

aws ssm create-activation \
  --default-instance-name <change-me> \
  --iam-role "<role-name>" \
  --registration-limit 1 \
  --region <region> \
  --expiration-date "2025-12-31T23:59:59" \
  --output json > non_aws_activation.json 2>&1
This creates non_aws_activation.json containing the activation-id and activation-code.

Adjust These Flags

Flag Description
--default-instance-name Logical name for the instance in SSM
--iam-role ARN of the IAM role to associate
--registration-limit Max number of instances to register with this activation, you can adjust this value as needed, this code can be reused until the limit is reached.
--region AWS region for Systems Manager
--expiration-date Expiry timestamp for the activation code
--output Format of output (JSON recommended)

Step 3: Activate the Instance

SSH into your non-AWS Linux instance where Bastion will run.

Install & Register SSM Agent

mkdir /tmp/ssm
curl https://amazon-ssm-<region>.s3.<region>.amazonaws.com/latest/debian_amd64/ssm-setup-cli -o /tmp/ssm/ssm-setup-cli
sudo chmod +x /tmp/ssm/ssm-setup-cli
sudo /tmp/ssm/ssm-setup-cli -register \
  -activation-code <activation-code> \
  -activation-id <activation-id> \
  -region <region> >> /tmp/ssm/ssm-activation.log 2>&1

Replace <activation-code> and <activation-id> with values from non_aws_activation.json Replace <region> with your AWS region (e.g., us-east-1).

This registers the instance with AWS SSM. Logs are saved to /tmp/ssm/ssm-activation.log.

Run:

cat /tmp/ssm/ssm-activation.log

Look for a line like:

Agent already registered with instance id: mi-xxxxx
Copy the mi-xxxxx — this is your Instance ID required for Bastion setup.

✅ You now have the required Instance ID for Bastion configuration.

Step 4: Install Docker

Docker is required to run the Bastion. Use the following guide if you haven’t installed it yet

Docker Installation Guide

Makesure Docker is installed and running:

sudo docker --version

ServerSage Bastion runs entirely inside a Docker container.

Step 5: Open Port 5000 (Optional you can change this)

ServerSage Bastion runs on port 5000.
Ensure this port is open in your AWS Security Group.

How to open ports in AWS

🔐 You may still want to restrict this port to internal or VPN-only traffic.

Step 6: Pull the ServerSage Docker Image

Download the latest ServerSage Bastion container:

docker pull serversageai/serversage-bastion:latest

Step 7: Run the Bastion Container

Launch the container with your configuration:

docker run -d \
  -e "PORT=5000" \
  -e "AWS_REGION=ap-xxx-x" \
  -e "AWS_INSTANCE_ID=i-xxx" \
  -e "API_KEY=12345" \
  -e "AWS_ACCESS_KEY_ID=xxx" \
  -e "AWS_SECRET_ACCESS_KEY=xxx" \
  -p 5000:5000 serversageai/serversage-bastion:latest

Environment Variables Explained

Variable Description
PORT Internal port for the Bastion container (default: 5000)
AWS_REGION AWS region of the target instance (e.g., ap-southeast-1)
AWS_INSTANCE_ID Hybrid instance ID this Bastion will manage
API_KEY Custom key to protect your Bastion endpoint (can be any unique value)
AWS_ACCESS_KEY_ID IAM user access key
AWS_SECRET_ACCESS_KEY IAM user secret key
-p 5000:5000 Maps container port 5000 to the host; adjust as needed

Step 8. Verify ServerSage Bastion is Running

Run a health check:

curl "http://localhost:5000/ping"
Expected response: 
{"message":"Serversage is up"}

✅ This confirms the Bastion is live and accepting requests.

Step 9: Register the Bastion in ServerSage Dashboard

  1. Log in to your ServerSage dashboard.
  2. Navigate to the Sidebar section.
  3. Choose Add Bastion.

Step 10: Register the Bastion in ServerSage Dashboard

  1. Log in to your ServerSage dashboard.
  2. Navigate to the Sidebar section.
  3. Choose Add Bastion.
  4. Fill in the required fields:
  5. Bastion Name: A unique name for your Bastion.
  6. Bastion URL: The public URL or IP address of your Bastion (e.g., http://your-ec2-public-dns:5000).
  7. InstanceID: The Instance ID you retrieved from the activation step (e.g., mi-xxxxx).
  8. Region: The AWS region where your Bastion is running (e.g., ap-southeast-1).
  9. API Key: The API key you set in the Docker run command.
  10. Click Save to register the Bastion.
  11. Your Bastion is now ready to manage AWS resources and run AI-powered instructions.