Session Manager for Shell Access Without SSH

Getting a shell on an EC2 instance traditionally means an open port 22, a distributed SSH key, and often a bastion host as a chokepoint. Session Manager replaces all of that with a secure, auditable, WebSocket-based session brokered entirely through the SSM service - no inbound port, no key to rotate, no bastion to maintain.

Recipe

StartSession is the SDK call that initiates a session against a managed instance. It is worth being precise about what this call actually returns: a session ID, a token, and a stream URL - not a live terminal.

# --- Python (boto3) ---
import boto3
 
ssm = boto3.client("ssm", region_name="us-east-1")
resp = ssm.start_session(Target="i-0abc123")
print(resp["SessionId"], resp["TokenValue"], resp["StreamUrl"])

// --- TypeScript (AWS SDK v3) ---
import { SSMClient, StartSessionCommand } from "@aws-sdk/client-ssm";
 
const ssm = new SSMClient({ region: "us-east-1" });
const resp = await ssm.send(new StartSessionCommand({ Target: "i-0abc123" }));
console.log(resp.SessionId, resp.TokenValue, resp.StreamUrl);

That SessionId/TokenValue/StreamUrl trio is exactly what the Session Manager plugin needs to open the actual interactive channel. The SDK call establishes the session server-side; it does not hand your Python or Node.js process a shell.

Working Example

In practice, the everyday path to an interactive terminal is the AWS CLI's aws ssm start-session command, which internally does the equivalent of the SDK call above and then hands the result to the locally installed Session Manager plugin, which speaks the WebSocket protocol and renders the terminal.

# --- Python (boto3) ---
import subprocess
 
# The CLI (with the Session Manager plugin installed) handles the
# actual interactive terminal; the SDK call above is what it does internally.
subprocess.run(["aws", "ssm", "start-session", "--target", "i-0abc123"])

// --- TypeScript (AWS SDK v3) ---
import { execSync } from "node:child_process";
 
// The CLI (with the Session Manager plugin installed) handles the
// actual interactive terminal; the SDK call above is what it does internally.
execSync("aws ssm start-session --target i-0abc123", { stdio: "inherit" });

Calling the CLI from your own code is a legitimate pattern for tooling that wraps start-session with your own instance-selection logic (for example, resolving an instance ID from a tag before invoking it). But if you find yourself parsing StreamUrl and hand-rolling the WebSocket protocol from the raw StartSession SDK response, stop - that protocol is exactly what the plugin already implements, and reimplementing it is not a supported or documented path.

Deep Dive

What StartSession Is Actually For

The direct SDK StartSession call is most useful for two things: (1) programmatically confirming a session can be established (permissions, connectivity, managed-instance status) before handing off to the CLI/plugin, and (2) building tooling that needs to start a session and pass its details to something else that speaks the Session Manager protocol - a browser-based terminal, for instance, is how the AWS Console's own "Connect" button works.

For a human simply wanting a shell, always route through aws ssm start-session (or the Console's Session Manager tab), not a bespoke SDK integration.

Document-Based Sessions

StartSession accepts an optional DocumentName for session types beyond a plain shell - AWS-StartPortForwardingSession tunnels a local port to a port on the instance (handy for reaching a database or admin UI that only listens on localhost), and AWS-StartSSHSession tunnels actual SSH traffic through the Session Manager channel for tools that expect SSH specifically.

# --- Python (boto3) ---
resp = ssm.start_session(
    Target="i-0abc123",
    DocumentName="AWS-StartPortForwardingSession",
    Parameters={"portNumber": ["5432"], "localPortNumber": ["15432"]},
)

// --- TypeScript (AWS SDK v3) ---
const resp = await ssm.send(new StartSessionCommand({
  Target: "i-0abc123",
  DocumentName: "AWS-StartPortForwardingSession",
  Parameters: { portNumber: ["5432"], localPortNumber: ["15432"] },
}));

As with the plain shell case, the plugin (via aws ssm start-session --document-name AWS-StartPortForwardingSession ...) is what actually opens and maintains the tunnel; the SDK call sets it up.

Ending and Auditing Sessions

TerminateSession ends a session by ID - useful for administrative cleanup, such as force-ending a session a departing engineer left open.

# --- Python (boto3) ---
ssm.terminate_session(SessionId=resp["SessionId"])

// --- TypeScript (AWS SDK v3) ---
await ssm.send(new TerminateSessionCommand({ SessionId: resp.SessionId }));

Every session start, end, and (if configured) full command output is logged. Session Manager preferences let you route session logs to CloudWatch Logs and/or an S3 bucket, and every action is recorded in CloudTrail regardless - giving you a durable record of who connected to what, when, without depending on SSH auth.log scattered across every instance.

Gotchas

• Expecting an interactive shell directly from the SDK response. StartSession returns connection details, not a terminal; the actual interactive session is established by the Session Manager plugin.
• Reimplementing the WebSocket protocol. Parsing StreamUrl/TokenValue yourself to build a custom terminal client duplicates what the plugin already does and is not a documented integration path.
• Forgetting the plugin is a separate install. aws ssm start-session fails with a clear error if the Session Manager plugin is not installed alongside the CLI - it is a separate download, not bundled.
• Assuming Session Manager needs no IAM. Both the caller (to start a session) and the instance's role (AmazonSSMManagedInstanceCore) need the right permissions; missing either fails the connection.
• Not enabling session logging. Without CloudWatch Logs or S3 logging configured in Session Manager preferences, you get session start/end audit events but not full command transcripts.
• Leaving stale sessions open. Idle sessions do time out, but explicit cleanup via TerminateSession is useful for immediate revocation (for example, offboarding).

Alternatives

• Traditional SSH with a bastion host still works and is well understood, but requires managing keys, an open port, and a bastion's own security posture that Session Manager eliminates entirely.
• Run Command is better when the task is a single predetermined command across many instances rather than open-ended interactive exploration.
• EC2 Instance Connect offers browser-based SSH for a single instance without a persistent key, but lacks Session Manager's centralized logging and its port-forwarding session type.

Session Manager is the right default for interactive access to managed instances in 2026: no inbound port, no key management, and a built-in audit trail that ad hoc SSH access does not provide.

FAQs

Related

• Systems Manager as the Fleet Operations Toolkit - how Session Manager fits with Parameter Store, Run Command, and Automation.
• Run Command for Fleet-Wide Execution - for a single predetermined command instead of interactive access.
• Systems Manager via SDK Best Practices - session logging and access-control habits.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).