Installation guide

This guide is for the platform team installing Cloud Certainty StateCraft in their AWS account. The install is one CloudFormation stack (the hub). Every other account whose state machines StateCraft should reach gets a small role stack (the spoke). With IAM Identity Center or another SAML IdP, the hub takes two steps: deploy the stack, configure the SAML application, then update the stack. For the short version, see Getting started.

#Before you start

• Region. Any Region with AWS Step Functions, AWS Lambda, Amazon API Gateway (HTTP APIs), Amazon DynamoDB, Amplify Hosting, Amazon Cognito, AWS License Manager and Amazon ECS on Fargate. Voice also needs Amazon Transcribe streaming in the stack's Region, and assist needs Amazon Bedrock with the Claude model in AssistRegion. The templates are always loaded from the vendor's public bucket in us-east-1 (CloudFormation accepts a template URL from any Region), and all product code comes from the container image. The hub's Region doesn't limit which Regions you can work in: list them in LocalRegions and in each connection.
• Account. Deploy the hub in the account that subscribed on AWS Marketplace: the licence is delivered to that account through AWS License Manager. To run the hub in another account of your organisation, distribute the licence to it with a License Manager grant first.
• Permissions. You need permission to create the resources in the stack: IAM roles (some have fixed names), Lambda, Step Functions, ECS, EC2 security groups, Cognito, API Gateway, Amplify, DynamoDB, S3, SNS, EventBridge, KMS and CloudWatch Logs.
• Network. A VPC with at least one subnet with outbound HTTPS access, for the one-off installer task (see Networking). Nothing else runs in your VPC.
• Identity. Decide how users will sign in: IAM Identity Center, another SAML 2.0 IdP (Entra ID, Okta and others), an OIDC IdP, or Cognito-managed users. SAML IdPs other than IAM Identity Center, and OIDC, need the Team plan or above.
• Your state machines. Decide the access level per account (Read, Operate or Full), note the execution roles your state machines use (StateCraft passes only the ones you list to Step Functions, see What StateCraft may do), and the customer managed KMS keys of any encrypted state machines.

#1. Subscribe

1. Open StateCraft in AWS Marketplace and choose Continue to Subscribe. Choose the plan and the contract length (Team is the base plan; Business and Enterprise are add-ons to it) and accept the offer. AWS License Manager now holds your licence.
2. Choose Continue to Configuration, select the fulfilment option and the Region, then open the CloudFormation launch link from the usage instructions.

#2. Launch the hub stack

In the CloudFormation console, fill in the parameters (see the reference). Acknowledge "AWS CloudFormation might create IAM resources with custom names" and create the stack. Creation takes about 10 minutes.

The quick-create link, with the release version filled in:

https://console.aws.amazon.com/cloudformation/home#/stacks/quickcreate?templateURL=https://cloudcertainty-statecraft-us-east-1.s3.us-east-1.amazonaws.com/pro/<version>/main.yaml&stackName=statecraft

From the AWS CLI (--region is the Region you deploy to):

aws cloudformation create-stack --region <your-region> --stack-name statecraft \
  --template-url https://cloudcertainty-statecraft-us-east-1.s3.us-east-1.amazonaws.com/pro/<version>/main.yaml \
  --parameters file://params.json \
  --capabilities CAPABILITY_IAM CAPABILITY_NAMED_IAM

params.json lists the parameters as [{"ParameterKey": "VpcId", "ParameterValue": "vpc-..."}, ...].

#What happens during creation

The product's code (the Lambda functions and the web app) ships inside the subscription-protected container image, not as public downloads. Early in stack creation:

1. CloudFormation creates a private S3 bucket in your account (output ArtifactsBucketName; all public access blocked, encrypted, TLS only).
2. The ArtifactInstall custom resource starts one Fargate task from the product image in your InstallerSubnetIds. The task checks your AWS Marketplace licence in AWS License Manager, verifies every file of the code bundle against the SHA-256 checksums in the image, and copies it into the bucket under the release's version. It runs for about a minute at 0.25 vCPU and 512 MB, with a read-only root filesystem and a security group without inbound rules.
3. The Lambda functions, StateCraft's own bulk jobs workflow (a Step Functions Standard state machine named <NamePrefix>-bulk, whose items run as Express child executions of a Distributed Map) and the web app are then created from that bucket.

If the installer task fails, stack creation fails and rolls back. The error message gives the task's exit code and its log stream (log group /<NamePrefix>/installer); see Troubleshooting.

#3. Connect your identity provider

Until SamlMetadataUrl is set, the portal falls back to Cognito sign-in, which has no users. Nobody can sign in at that point, so the stack is safe in that state.

#4. First sign-in

Open the PortalUrl output and sign in as BootstrapAdminEmail. The first account that signs in with that (verified) email becomes the bootstrap administrator and stays bound to it (see the admin guide).

The local connection to the hub's own account exists from the start. It uses the stack's local role, which may do what LocalAccessLevel allows, in the Regions of LocalRegions. Administrators see every state machine there. Other users see nothing until an administrator grants them access (admin guide).

#What StateCraft may do

The local role and every spoke role are the upper limit of what StateCraft can do in an account, for everyone, administrators included. StateCraft then narrows each request to the person's grants with a session policy.

With Read, nobody can change anything through StateCraft, whatever their grants. People without the data permission see executions without their inputs, outputs and error causes: StateCraft asks Step Functions for metadata only, and for state machines encrypted with a customer managed key, their AWS session can't decrypt the data either.

The roles have no IAM permissions other than iam:PassRole to Step Functions, and no CloudFormation, DynamoDB or StateCraft bucket permissions, so StateCraft can't change its own stack.

#Voice

With Voice = Enabled (the default), the stack creates a role used only to sign Amazon Transcribe streaming sessions in the stack's Region (transcribe:StartStreamTranscriptionWebSocket, nothing else). When someone presses the microphone, the API signs a WebSocket URL valid for 5 minutes for that person, and the browser streams the audio straight to Amazon Transcribe in your account. StateCraft never stores audio or transcripts. Administrators choose the speech engine and language under Administration › Settings (admin guide).

What your environment needs for voice:

• Amazon Transcribe streaming in the stack's Region, and no SCP that denies it.
• Microphone permission. Browsers ask each person once per site. Managed browsers may block the microphone by policy (in Chrome and Edge, AudioCaptureAllowed and AudioCaptureAllowedUrls); allow it for the PortalUrl.
• Content Security Policy. The portal's CSP allows the browser to connect only to your sign-in, your API and wss://transcribestreaming.<stack region>.amazonaws.com:8443, and its Permissions-Policy allows the microphone for the portal itself only. If you put a proxy or your own security headers in front of the portal, keep both, or voice stops working (typed commands still work).
• Network. Users' networks must allow outbound WebSocket connections on port 8443 to that endpoint.
• Data use. Amazon Transcribe may use content it processes to improve AWS services unless your organisation has an AWS Organizations AI services opt-out policy. Set one if your policy requires it.

With Voice = Disabled, no voice role is created and the Amazon Transcribe engine is unavailable; typed commands still work, and an administrator can still choose the browser's own speech service (which sends audio to the browser vendor, outside your AWS account).

#Assist

Assist (Business plan and above) turns a description into a workflow, or a change to one, with Claude on Amazon Bedrock in your account. It is off until an administrator turns it on under Administration › Settings. To use it:

1. Pick the model and Region. AssistModelId is the Bedrock model id, by default Claude Opus 5.5 (anthropic.claude-opus-5-5); empty turns assist off and grants no Bedrock permission. AssistRegion is the Region of the Bedrock endpoint, by default the stack's Region. StateCraft calls the Amazon Bedrock Mantle endpoint (bedrock-mantle.<region>.api.aws), and the stack's API role may call only that model there (bedrock-mantle:CreateInference).
2. Make the model available to the account. In the Amazon Bedrock console of AssistRegion, check that the model is available to your account; the first use of an Anthropic model may ask you to submit your use case details once. Make sure no SCP denies Amazon Bedrock (bedrock-mantle:*) in that Region.
3. Turn assist on under Administration › Settings.

Each request sends only the person's description and, for a change, the current definition; the result comes back as a diff that the person accepts or rejects. Bedrock bills the tokens to your account. If the model isn't available, assist shows the AWS error and nothing else is affected.

#5. Deploy the spoke role in other accounts

spoke-role.yaml creates one role, /statecraft/<RoleName>, that only the hub's API role and its bulk job worker role (stack output SpokeTrustedPrincipal) can assume, only with your external ID, and only with a user's email as the source identity. IAM is global, so deploy it once per account; the connection then covers every Region you list. Its template URL is the stack output SpokeTemplateUrl:

https://cloudcertainty-statecraft-us-east-1.s3.us-east-1.amazonaws.com/pro/<version>/spoke-role.yaml

The role is the upper limit of what StateCraft can do in that account; grants narrow it per user or group but never widen it. The stack's outputs are RoleArn (enter it in the connection) and AccessLevel (choose the same level for the connection).

#A single account

cat > spoke-params.json <<'EOF'
[
  {"ParameterKey": "TrustedPrincipal", "ParameterValue": "<SpokeTrustedPrincipal output>"},
  {"ParameterKey": "ExternalId", "ParameterValue": "<a secret of at least 16 characters>"},
  {"ParameterKey": "AccessLevel", "ParameterValue": "Operate"},
  {"ParameterKey": "PassRoleArns", "ParameterValue": "arn:aws:iam::<account>:role/sfn-*"}
]
EOF
aws cloudformation create-stack --region eu-west-1 --stack-name statecraft-spoke \
  --template-url https://cloudcertainty-statecraft-us-east-1.s3.us-east-1.amazonaws.com/pro/<version>/spoke-role.yaml \
  --parameters file://spoke-params.json --capabilities CAPABILITY_NAMED_IAM

#Every account of an AWS Organization (StackSets)

With service-managed StackSets, new accounts in the target OUs get the role automatically. Use one external ID for the whole StackSet, and enter that same external ID for every connection you create for those accounts. PassRoleArns patterns without an account ID (for example arn:aws:iam::*:role/sfn-*) suit a StackSet.

# From the management account or a delegated StackSets administrator.
aws cloudformation create-stack-set --region us-east-1 --stack-set-name statecraft-spoke \
  --template-url https://cloudcertainty-statecraft-us-east-1.s3.us-east-1.amazonaws.com/pro/<version>/spoke-role.yaml \
  --parameters file://spoke-params.json \
  --capabilities CAPABILITY_NAMED_IAM \
  --permission-model SERVICE_MANAGED \
  --auto-deployment Enabled=true,RetainStacksOnAccountRemoval=false

# One Region is enough: IAM is global.
aws cloudformation create-stack-instances --region us-east-1 --stack-set-name statecraft-spoke \
  --deployment-targets OrganizationalUnitIds=ou-abcd-11111111 --regions eu-west-1

Service-managed StackSets don't deploy to the management account; use a normal stack there if StateCraft should reach it. To change AccessLevel later, update the StackSet, then the access level of the connections.

#Add the connection

In Administration › Connections › Add connection, enter an id (used in links, it can't be changed later), a name, the account ID, the access level, the spoke stack's RoleArn, the external ID and the Regions. Choose Test: StateCraft assumes the role and counts the state machines in each Region. See the admin guide.

#Parameter reference

#Networking

Only the installer task runs in your VPC, for about a minute at install and at each upgrade. It needs outbound HTTPS (443) to:

• Amazon ECR in us-east-1, to pull the image from the AWS Marketplace registry (cross-Region, so this needs internet egress: a NAT gateway or public subnets);
• AWS License Manager in your Region, for the licence check;
• Amazon S3 in your Region, to write the code into the artifacts bucket (a gateway endpoint works);
• CloudWatch Logs in your Region, for its log stream.

Its security group has no inbound rules and one outbound rule, TCP 443. The Lambda functions don't run in your VPC; they reach Step Functions, CloudWatch, CloudWatch Logs, STS and, for assist, Amazon Bedrock in your accounts over AWS's public endpoints. Voice audio goes from users' browsers straight to Amazon Transcribe in the stack's Region.

#Encryption and KMS

Without KmsKeyArn, the DynamoDB tables, the log groups, the update SNS topic, the artifacts bucket and the bulk jobs workflow use AWS owned keys and SSE-S3.

With KmsKeyArn, your key encrypts all of them. The key must be a symmetric customer managed key in the stack's Region (give its ARN, not an alias), and its key policy must:

• let the account's IAM policies grant its use (the default key policy statement for the account root does this). The stack's roles use it only through DynamoDB, CloudWatch Logs, SNS, S3 and Step Functions;
• allow logs.<region>.amazonaws.com to use it for the stack's log groups, and delivery.logs.amazonaws.com for the bulk jobs workflow's log delivery;
• allow sns.amazonaws.com to use it for the update topic.

The identity that creates or updates the stack also needs kms:Decrypt on the key, because Lambda reads the function code from the encrypted artifacts bucket with the deploying identity's permissions.

The key protects StateCraft's own data. Your state machines keep their own encryption; list their keys in StateMachineKmsKeyArns.

#Stack outputs

#Updating

Each release is a new template; there is no version parameter. To upgrade, update the stack with the new release's template (Update stack › Replace current template) and keep every other parameter value. See the upgrading guide.

To change a setting such as LocalAccessLevel, LocalRegions, PassRoleArns, Voice or SamlMetadataUrl, update the stack with the current template and change only that parameter.

#Deleting

1. Delete the hub stack. The DynamoDB table (<NamePrefix>-table) is retained on purpose, with its settings, grants, drafts, saved inputs, execution records, bulk jobs and audit log. Everything else is deleted: the cache table (with the usage counters), the Cognito user pool (Cognito-only users are lost), the artifacts bucket, the bulk jobs workflow and the log groups. A new stack with the same NamePrefix can't be created while the retained table exists.

   To delete the table when you no longer need it, turn off its deletion protection, then delete it. Your own state machines are never touched by deleting StateCraft.

2. Delete the spoke stacks or the StackSets in the other accounts.

3. Delete the SAML or OIDC application in your identity provider.

#Troubleshooting