Onboarding and AWS Connection Linking

This guide describes the Runless SaaS onboarding path. The customer-side Quick Start stack creates a scoped cross-account role, then you complete account linking in the Runless portal.

Overview

Connection onboarding has three phases:

  1. Launch Quick Start in the customer AWS account
  2. Complete connection linking in the Runless portal using stack outputs
  3. Verify + reconcile role access and commercial status

Prerequisites

  • Access to AWS Marketplace and customer AWS account
  • Ability to deploy the Runless Quick Start stack
  • Runless account with tenant owner or member access

Required Onboarding Values

From Quick Start stack outputs:

  • CustomerAwsAccountId
  • RoleArn
  • InstallationId
  • ExternalId
  • StackId
  • PortalLinkUrl (preferred direct entry path)

Step-by-Step Onboarding

1

Launch Quick Start

2
  1. Subscribe to Runless in AWS Marketplace.
  2. Launch the onboarding stack in the AWS account you want to manage.
  3. Wait for stack completion and open the Outputs tab.
3

Open the Runless portal

4
  1. Open PortalLinkUrl from stack outputs.
  2. Sign in or create your Runless account.
  3. Confirm the pre-filled onboarding values.
5

Complete account linking

6
  1. Submit the onboarding form.
  2. Runless stores the connection as PENDING_VERIFICATION.
  3. Runless attempts role assumption using ExternalId.
7

Verify and activate

8
  1. If verification passes, connection status becomes VERIFIED.
  2. Runless reconciles commercial access.
  3. When commercial access is active, automation features are fully enabled.

Connection Statuses

StatusMeaningTypical action
PENDING_VERIFICATIONAccount is linked but role verification is not completeRetry verification after IAM fixes
FAILEDVerification failedCheck trust policy, external ID, and role permissions
VERIFIEDRole verification succeededContinue with inventory/rules setup
PENDING_COMMERCIAL_ACCESSRole verified, subscription state not confirmed yetRetry commercial access check
INACTIVE_COMMERCIAL_ACCESSRole verified, but no active product accessUpdate subscription status

Troubleshooting

Verification fails

Check:

  • Role trust includes the Runless product account
  • sts:ExternalId condition matches the supplied ExternalId
  • Role policy includes required ECS read + runtime actions

Commercial access is pending or inactive

Check:

  • Marketplace subscription for the target account
  • Correct product and account pairing
  • Retry verification from the dashboard after commercial updates

Manual form entry

If PortalLinkUrl is unavailable, open the registration flow from Runless and paste all required outputs manually.

Next Steps

  1. Team & Access Management - Invite your team and assign roles
  2. Application Manual - Configure schedules and runtime controls