bastion tunnel

The bastion tunnel command creates a secure tunnel through a bastion host to reach resources inside a private VPC. Use it to connect local tools — database GUIs, Redis CLIs, or HTTP clients — to resources that have no public endpoint. The command establishes the tunnel through AWS SSM Session Manager.

Usage

stacktape bastion tunnel myDatabase --stage prod --region eu-west-1

The command opens one or more local ports, prints the local-to-remote mapping, and keeps running until you press Ctrl+C. Your stack must contain a bastion resource.

Important flags

<resource-name> (required, positional argument) — the name of the target resource you want to reach through the tunnel, as defined in your Stacktape configuration.

--bastion-resource — selects which bastion resource to tunnel through. Use this when your stack has multiple bastion hosts.

--local-tunneling-port — sets the local port passed to the tunneling helper. If not specified, Stacktape automatically selects an available port. If the target resolves to multiple tunnel targets, Stacktape opens one port-forwarding session per target and prints the actual local ports.

Flags reference

stacktape bastion tunnel <resource-name>CLI options
-r, --regionrequired"us-east-2" | "us-east-1" | "us-west-1" | "us-west-2" | "ap-east-1" | "ap-south-1" | "ap-northeast-3" | "ap-northeast-2" | "ap-southeast-1" | "ap-southeast-2" | "ap-northeast-1" | "ca-central-1" | "eu-central-1" | "eu-west-1" | "eu-west-2" | "eu-west-3" | "eu-north-1" | "me-south-1" | "sa-east-1" | "af-south-1" | "eu-south-1"

AWS Region

The AWS region for the operation. For a list of available regions, see the AWS documentation.

Inside a project whose config declares region, the flag is optional and overrides the config.

--resource-name (positional 1)requiredstring

Resource Name

The name of the resource as defined in your Stacktape configuration.

-s, --stagerequiredstring

Stage

The stage for the operation (e.g., production, staging, dev-john). You can set a default stage using the defaults set command. Stage names use lowercase letters, numbers and dashes, with at least 2 characters. The project name, a dash and the stage form the CloudFormation stack name, which can have at most 128 characters. Stacktape shortens an AWS resource name that would be too long and adds a hash.

--aws-accountstring

AWS Account

The name of the AWS account to use for the operation. The account must first be connected in the Stacktape Console.

Without it, the account is chosen by --profile, AWS_PROFILE or AWS credentials in environment variables, then by your saved default, then by your organization's only connected account. --aws-account takes precedence over all of them, but AWS credentials in environment variables must then belong to that account.

--bastion-resourcestring

Bastion Resource Name

The name of the bastion resource as defined in your Stacktape configuration.

-c, --configstring

Config File Path

The path to your Stacktape configuration file, relative to the current working directory. Without it, Stacktape uses the one stacktape.ts, stacktape.yml, stacktape.yaml or stacktape.js in the working directory. When there are several, the command stops and asks you to choose one with this option.

--cwdstring

Current Working Directory

The working directory for the operation. All file paths in your configuration will be resolved relative to this directory. By default, this is the directory containing the configuration file.

-h, --helpstring

Show Help

If provided, the command will not execute and will instead print help information.

--local-tunneling-portnumber

Local Tunneling Port

Specifies the local port for tunneling when using the bastion tunnel command. If not specified, Stacktape automatically selects an available port.

--log-level"info" | "debug" | "error"

Log Level

The level of logs to print to the console.

  • info: Basic information about the operation.
  • error: Only errors.
  • debug: Detailed information for debugging.
-p, --profilestring

AWS Profile

The AWS profile to use for the command. You can manage profiles using the aws-profile:* commands and set a default profile with defaults set.

For commands that use a connected AWS account, --profile (or AWS_PROFILE) selects the connected account the profile belongs to, unless --aws-account is set. The command fails if that account is not connected.

--projectstring

Project Name

The name of the Stacktape project for this operation.

Commands that target a stack take it from projectName in the project's config when the flag is absent.

--quietboolean

Quiet

Hide progress, banners, success messages and hints. Command output, warnings and errors are still printed.

Supported resource types

Bastion tunneling works with four resource types. Stacktape resolves the tunnel targets for the resource and opens one or more port-forwarding sessions accordingly.

Resource typeNotes
relational-databaseTunnels to the database endpoints resolved for the resource.
redisTunnels to the Redis endpoints resolved for the resource.
application-load-balancerTunnels to the load balancer's listener ports.
private-serviceTunnels through the private service's nested load balancer. Requires the deployed private service to have a nested load balancer.

If you target a resource type not listed above, Stacktape fails the command with an unsupported-tunnel-target error.

Examples

Tunnel to a relational database

Connect a local database GUI (pgAdmin, DataGrip, DBeaver) to a VPC-only PostgreSQL or MySQL database.

stacktape bastion tunnel myDatabase --stage prod --region eu-west-1

The output prints each local-to-remote mapping. When tunnel metadata includes an additional string, Stacktape prints it with the remote host and port replaced by the local tunnel address.

Tunnel on a specific local port

Pin the local port so bookmarked database connections stay stable across sessions.

stacktape bastion tunnel myDatabase --stage prod --region eu-west-1 --local-tunneling-port 5433

Stacktape starts one port-forwarding session for each resolved target and prints the local port for each tunnel.

Tunnel to a Redis cache

Access a VPC-only Redis cache from a local redis-cli or Redis GUI.

stacktape bastion tunnel myRedis --stage prod --region eu-west-1

Tunnel to a private service

Reach a private service through its load balancer.

stacktape bastion tunnel myPrivateApi --stage prod --region eu-west-1

Specify which bastion to use

When a stack has multiple bastion hosts, pass the bastion name explicitly with --bastion-resource.

stacktape bastion tunnel myDatabase --stage prod --region eu-west-1 --bastion-resource devBastion

How tunneling works

When you run bastion tunnel, Stacktape performs the following steps:

  1. Initializes services for working with the deployed stack.
  2. Looks up the target resource by name in the deployed stack. If the resource does not exist, the command fails with an error.
  3. Validates that the target is a supported resource type. For private-service, it also checks that the resource has a nested load balancer.
  4. Resolves the tunnel targets for the resource (hosts, ports, and optional connection string metadata) using the target resource name and the bastion resource name.
  5. Passes --local-tunneling-port as the starting port to the port-forwarding session helper, which opens one SSM session per resolved target.
  6. Prints the local-to-remote mappings, including substituted connection strings when available.
  7. Registers cleanup hooks to close all tunnel sessions on exit.
  8. Keeps the process alive until you press Ctrl+C.

The tunnel uses AWS SSM Session Manager under the hood, through AWS's Session Manager plugin. You do not install it yourself. The Windows installer includes it; on Linux and macOS, the first command that needs it downloads the version Stacktape pins from AWS, checks its SHA-256 against the checksum that Stacktape release pins, and keeps it under ~/.stacktape/tools for later commands. On a machine without internet access, place the plugin there beforehand: when the download fails, the error names the URL, the expected checksum and the exact path.

bastion tunnel FAQ

Do I need SSH keys to use bastion tunnel?

No. The bastion tunnel command uses AWS SSM Session Manager for port forwarding, not SSH, so there are no SSH keys to manage. Stacktape supplies the Session Manager plugin the tunnel needs (see How tunneling works), and your stack must include a bastion resource.

How do I connect a database GUI through the tunnel?

Run bastion tunnel and note the local address printed in the output (e.g. 127.0.0.1:5433). In your database GUI, set the host to 127.0.0.1 and the port to the printed local port. Use the same database credentials you normally use for the deployed resource; bastion tunnel only changes the host and port to the printed local address.

Why does my private service tunnel fail?

Tunneling to a private service requires the deployed service to have a nested load balancer. If your private service does not have one, the command fails with an error. The other supported targets are relational-database, redis, and application-load-balancer; any other resource type fails with an unsupported-tunnel-target error.

Can I run multiple tunnels at the same time?

Yes. Each bastion tunnel invocation keeps running while its port-forwarding sessions are open, so run another invocation in a separate terminal for a second tunnel. Pass a different --local-tunneling-port to each one to avoid local port collisions.

Can I tunnel to a publicly accessible database?

You can, but there is no reason to. If a database has a public endpoint, connect to it directly. Bastion tunneling is designed for resources deployed in a private VPC with no public endpoint.

  • bastion shell — start an interactive shell session on the bastion host itself.
  • query sql — run read-only SQL queries against a deployed database. Supports --bastion-resource for VPC-only databases.
  • query redis — query a deployed Redis cache. Supports --bastion-resource for VPC-only clusters.