Console

Manage and monitor your apps with the SST Console.

The Console is a web based dashboard to manage your SST apps. With it you can invoke functions, debug issues, view logs, and git push to deploy your apps, with your team — console.sst.dev

Get started

Start by creating an account and connecting your AWS account.

Create an account with your email

It’s better to use your work email so that you can invite your team to your workspace later — console.sst.dev
Create a workspace

You can add your apps and invite your team to a workspace. A workspace can be for a personal project or for your team at work. You can create as many workspaces as you want.

Create a workspace for your organization. You can use it to invite your team and connect all your AWS accounts.
Connect your AWS account

This will ask you to create a CloudFormation stack in your AWS account. Make sure that this stack is being added to us-east-1. Scroll down and click Create stack.

The CloudFormation stack needs to be created in us-east-1. If you create it in the wrong region by mistake, remove it and create it again.

This stack will scan all the regions in your account for SST apps and subscribe to them. Once created, you’ll see all your apps, stages, and the functions in the apps.
Invite your team

Use the email address of your teammates to invite them. They just need to login with the email you’ve used and they’ll be able to join your workspace.

How it works

At a high level, here’s how the Console works.

It’s hosted on our side

It stores some metadata about what resources you have deployed. We’ll have a version that can be self-hosted in the future.
You can view all your apps and stages

Once you’ve connected your AWS accounts, it’ll deploy a separate CloudFormation stack and connect to any SST apps in it. And all your apps and stages will show up automatically.
You can manage your apps

You can view all the functions in your app. You can view all the issues in your functions in real-time with the source maps automatically applied. You can view their logs, invoke them, or replay invocations. You can also save event payloads to your workspace.

For your functions running Live, the logs will be streamed in real-time from your local machine.
It’s open-source, built with SST, and deployed with Seed

The Console is a full-stack SST app. You can view the source on GitHub.

Security

The CloudFormation stack that the Console uses, creates an IAM Role in your account to manage your resources. If this is a concern for your production environments, we have a couple of options.

By default, this role is granted AdministratorAccess, but you can customize it to restrict access. We’ll look at this below. Additionally, if you’d like us to sign a BAA, feel free to contact us.

There maybe cases where you don’t want any data leaving your AWS account. For this, we’ll be supporting self-hosting the Console in the future.

IAM permissions

Permissions for the Console fall into two categories: read and write:

Read Permissions: The Console needs specific permissions to display information about resources within your SST apps.

Purpose	AWS IAM Action
Fetch stack outputs	`cloudformation:DescribeStacks`
Retrieve function runtime and size	`lambda:GetFunction`
Access stack metadata	`ec2:DescribeRegions` `s3:GetObject` `s3:ListBucket`
Display function logs	`logs:DescribeLogStreams` `logs:FilterLogEvents` `logs:GetLogEvents` `logs:StartQuery`
Monitor invocation usage	`cloudwatch:GetMetricData`

Attach the arn:aws:iam::aws:policy/ReadOnlyAccess AWS managed policy to the IAM Role for comprehensive read access.

Write Permissions: The Console requires the following write permissions.

Purpose	AWS IAM Action
Forward bootstrap bucket events to event bus	`s3:PutBucketNotification`
Send events to Console	`events:PutRule` `events:PutTargets`
Grant event bus access for Console	`iam:CreateRole` `iam:DeleteRole` `iam:DeleteRolePolicy` `iam:PassRole` `iam:PutRolePolicy`
Enable Issues to subscribe logs	`logs:CreateLogGroup` `logs:PutSubscriptionFilter`
Invoke Lambda functions and replay invocations	`lambda:InvokeFunction`

It’s good practice to periodically review and update these policies.

Customize policy

To customize IAM permissions for the CloudFormation stack:

On the CloudFormation create stack page, download the default template.json.

Edit the template file with necessary changes.

View the template changes

"SSTRole": {
  "Type": "AWS::IAM::Role",
  "Properties": {
    ...
    "ManagedPolicyArns": [
      "arn:aws:iam::aws:policy/AdministratorAccess"
      "arn:aws:iam::aws:policy/ReadOnlyAccess"
    ],
    "Policies": [
      {
        "PolicyName": "SSTPolicy",
        "PolicyDocument": {
          "Version": "2012-10-17",
          "Statement": [
            {
              "Effect": "Allow",
              "Action": [
                "s3:PutBucketNotification"
              ],
              "Resource": [
                "arn:aws:s3:::sstbootstrap-*"
              ]
            },
            {
              "Effect": "Allow",
              "Action": [
                "events:PutRule",
                "events:PutTargets"
              ],
              "Resource": {
                "Fn::Sub": "arn:aws:events:*:${AWS::AccountId}:rule/SSTConsole*"
              }
            },
            {
              "Effect": "Allow",
              "Action": [
                "iam:CreateRole",
                "iam:DeleteRole",
                "iam:DeleteRolePolicy",
                "iam:PassRole",
                "iam:PutRolePolicy"
              ],
              "Resource": {
                "Fn::Sub": "arn:aws:iam::${AWS::AccountId}:role/SSTConsolePublisher*"
              }
            },
            {
              "Effect": "Allow",
              "Action": [
                "logs:CreateLogGroup",
                "logs:PutSubscriptionFilter"
              ],
              "Resource": {
                "Fn::Sub": "arn:aws:logs:*:${AWS::AccountId}:log-group:*"
              }
            },
            {
              "Effect": "Allow",
              "Action": [
                "lambda:InvokeFunction"
              ],
              "Resource": {
                "Fn::Sub": "arn:aws:lambda:*:${AWS::AccountId}:function:*"
              }
            }
          ]
        }
      }
    ]
  }
}

Upload your edited template.json file to an S3 bucket.
Return to the CloudFormation create stack page and replace the template URL in the page URL.

Pricing

The Console pricing is based on the number of times the Lambda functions in your SST apps are invoked per month and it uses the following tiers.

Invocations	Rate (per invocation)
First 1M	Free
1M - 10M	$0.00002
10M+	$0.000002

A couple of things to note.

These are calculated for a given workspace on a monthly basis.
This does not apply to personal stages, they’ll be free forever.
There’s also a soft limit for Issues on all accounts.
For volume pricing, feel free to contact us.

Features

Here are a few of the things the Console does for you.

Logs: View logs from the functions in your app
Issues: Get real-time alerts for any errors in your functions
Local logs: View logs from your local sst dev session
Resources: View the resources in your app and their history
Autodeploy: Auto-deploy your app when you git push to your repo

Logs

With the Console, you don’t need to go to CloudWatch to look at the logs for your functions, containers and other log groups. You can view:

Past logs
Live logs
Jump to a specific time

SST Console logs

Issues

The Console will automatically show you any errors in your Node.js Lambda functions in real-time. And notify you through Slack or email.

SST Console Issues

With Issues, there is:

Nothing to setup, no code to instrument
Source maps are supported automatically
No impact on performance or cold starts, since the functions aren’t modified

Issues currently only supports Node.js functions. Other runtimes and containers are on the roadmap.

Behind the scenes

Here’s how it works.

When an app is deployed or when an account is first synced, we add a log subscriber to your Lambda functions.
- There’s a maximum of 2 subscribers allowed. More on this below.
The subscriber filters for anything that looks like an error and processes those log lines.
It applies the source maps to the error stack trace.
Finally, it groups similar looking errors together.

Log subscriber

The process of adding a log subscriber to your Lambda functions might fail. This can happen if:

We don’t have enough permissions to add a subscriber. In this case, update the permissions that you’ve granted to the Console.
We’ve hit the limit for the number of subscribers. To fix this, you can remove one of the existing subscribers.

You can see these errors in the Issues tab. Once you’ve fixed these issues, you can hit Retry and it’ll try attaching the subscriber again.

Error detection

Issues reports Lambda function failures. In addition, for Node.js it reports errors that are logged using console.error(new Error("my-error")).

For the Console to automatically report your errors, you need to pass in an error object with the console.error call.

console.error(new Error("my-error"));

Limits

There’s a soft limit of 10K issues per hour per workspace. If your account goes over this limit, Issues will be temporarily paused. You can contact us if this happens.

Local logs

When the Console starts up, it checks if you are running sst dev locally. If so, then it’ll show you real-time logs from your local terminal. This works by connecting to a local server that’s run as a part of the SST CLI.

SST Console local logs

The local server only allows access from localhost and console.sst.dev.

The local logs works in all browsers and environments. But for certain browsers like Safari or Brave, and Gitpod, it needs some additional configuration.

Safari & Brave

Certain browsers like Safari and Brave require the local connection between the browser and the sst dev CLI to be running on HTTPS.

SST can automatically generate a locally-trusted certificate using the sst cert command.

sst cert

You’ll only need to run this once on your machine.

Gitpod

If you are using Gitpod, you can use the Gitpod Local Companion app to connect to the sst dev process running inside your Gitpod workspace.

To get started:

Install Gitpod Local Companion app
Run the Companion app
Navigate to Console in the browser

The companion app runs locally and creates a tunnelled connection to your Gitpod workspace.

Resources

The Console shows you the complete state of the resources in your app. You can view:

Each resource in your app
The relation between resources
The outputs of a given resource
The full URN of the resource
The update where the resource was created or modified

SST Console resources

Update history

The Console also tracks all the updates that were made to your app. And the resources that were modified as a part of the update.

It also shows the SST command that was run that triggered the update. If the update was a part of an Autodeploy, it shows the related git commit as well.

Autodeploy

The Console can auto-deploy your apps when you git push to your GitHub repo. Autodeploy uses AWS CodeBuild in your account to run the build.

SST Console Autodeploy

We designed Autodeploy to be a better fit for SST apps when compared to alternatives like GitHub Actions or CircleCI.

Easy to get started
- Autodeploy supports the standard branch and PR workflow out of the box. You don’t need a config file to get started.
- There are no complicated steps in configuring your AWS credentials; since your AWS account is already connected to the Console.
Configurable
- You can configure how Autodeploy works directly through your sst.config.ts.
- It’s typesafe and the callbacks let you customize how to respond to incoming git events.
Runs in your AWS account
- The builds are run in your AWS account.
- It can also be configured to run in your VPC. This is useful if your builds need to access private resources.
Integrates with the Console
- You can see which resources were updated in a deploy.
- Your resource updates will also show you the related git commit.

Autodeploy is free while in beta. But AWS will charge you for the CodeBuild build minutes that are used. Learn more about CodeBuild pricing.

Setup

To get started with Autodeploy:

Enable the GitHub integration

Head over to your Workspace settings > Integrations and enable GitHub. This will ask you to login to GitHub and you’ll be asked to pick the GitHub organization or user you want to link to.

You can only associate your workspace with a single GitHub org.

If you have multiple GitHub orgs, you can create multiple workspaces in the Console.
Connect a repo

To auto-deploy an app, head over to the App’s Settings > Autodeploy and select the repo for the app.
Configure an environment

Next you can configure a branch or PR environment by selecting the stage you want deployed to an AWS account. You can optionally configure environment variables as well.

Stage names by default are generated based on the branch or PR.

By default, stages are based on the branch name or PR. We’ll look at this in detail below.
Git push

Finally, git push to the environment you configured and head over to your app’s Autodeploy tab to see it in action.

PR stages are removed when the PR is closed while branch stages are not.

For example, if you configure a branch environment for the stage production, any git pushes to the production branch will be auto-deployed. Similarly, if you create a new PR, say PR#12, the Console will auto-deploy a stage called pr-12.

You can also manually trigger a deployment through the Console by passing in a Git ref and the stage you want to deploy to.
Setup alerts

Once your deploys are working, you can set the Console to send alerts for your deploys. Head over to your Workspace Settings > Alerts and add a new alert to be notified on any Autodeploys, or only on Autodeploy errors.

While Autodeploy supports the standard branch and PR workflow out of the box, it can be configured in depth through your sst.config.ts.

Configure

The above can be configured through the console.autodeploy option in the sst.config.ts.

export default $config({
  // Your app's config
  app(input) { },
  // Your app's resources
  async run() { },
  // Your app's Console config
  console: {
    autodeploy: {
      target(event) {
        if (event.type === "branch" && event.branch === "main" && event.action === "pushed") {
          return { stage: "production" };
        }
      }
    }
  }
});

In the above example we are using the console.autodeploy.target option to change the stage that’s tied to a git event. Only git pushes to the main branch to auto-deploy to the production stage.

This works because if target returns undefined, the deploy is skipped. And if you provide your own target callback, it overrides the default behavior.

Through the console.autodeploy.runner option, you can configure the runner that’s used. For example, if you wanted to increase the timeouts to 2 hours, you can.

console: {
  autodeploy: {
    runner: { timeout: "2 hours" }
  }
}

This also takes the stage name, so you can set the runner config for a specific stage.

console: {
  autodeploy: {
    runner(stage) {
      if (stage === "production") return { timeout: "3 hours" };
    }
  }
}

You can also have your builds run inside your VPC.

console: {
  autodeploy: {
    runner: {
      vpc: {
        id: "vpc-0be8fa4de860618bb",
        securityGroups: ["sg-0399348378a4c256c"],
        subnets: ["subnet-0b6a2b73896dc8c4c", "subnet-021389ebee680c2f0"]
      }
    }
  }
}

Or specify files and directories to be cached.

console: {
  autodeploy: {
    runner: {
      cache: {
        paths: ["node_modules", "/path/to/cache"]
      }
    }
  }
}

Read more about the console.autodeploy config.

Environments

The Console needs to know which account it needs to autodeploy into. You configure this under the App’s Settings > Autodeploy. Each environment takes:

Stage

The stage that is being deployed. By default, the stage name comes from the name of the branch. Branch names are sanitized to only letters/numbers and hyphens. So for example:
- A push to a branch called production will deploy a stage called production.
- A push to PR#12 will deploy to a stage called pr-12.
As mentioned, above you can customize this through your sst.config.ts.

You can specify a pattern to match the stage name in your environments.

If multiple stages share the same environment, you can use a glob pattern. For example, pr-* matches all stages that start with pr-.
AWS Account

The AWS account that you are deploying to.
Environment Variables

Any environment variables you need for the build process. These are made available under process.env.* in your sst.config.ts.

How it works

When you git push to a branch, pull request, or tag, the following happens:

The stage name is generated based on the console.autodeploy.target callback.
1. If there is no callback, the stage name is a sanitized version of the branch or tag.
2. If there is a callback but no stage is returned, the deploy is skipped.
The stage is matched against the environments in the Console to get the AWS account and any environment variables for the deploy.
The runner config is generated based on the console.autodeploy.runner. Or the defaults are used.
The deploy is run based on the above config.

This only applies only to git events. If you trigger a deploy through the Console, you are asked to specify the stage you want to deploy to. So in this case, it skips step 1 from above and does not call console.autodeploy.target.

Both target and runner are optional and come with defaults, but they can be customized.

FAQ

Do I need to use the Console to use SST?

You don’t need the Console to use SST. It displays the local logs from your terminal in a UI that’s more convenient.
What if I don’t want to pay for the Console?

You can still invite your team and use it to view your local logs and stages.
Do I need a credit card to get started?

The Console is free to get started and doesn’t need a credit card.
Which Lambda functions are included in the number of invocations?

The number of invocations are only counted for the Lambda functions in your SST apps. Other Lambda functions in your AWS accounts are not included.
Do the functions in my personal stages count as a part of the invocations?

Lambda functions that are invoked locally are not included.
Can I access the personal stages if I’m above the free tier?

If you go above the free tier in your production stages, you can still access your personal stages. Just make sure you have sst dev running locally, otherwise the Console won’t be able to detect that it’s a personal stage.
My invocation volume is far higher than the listed tiers. Are there any other options?

Feel free to contact us and we can figure out a pricing plan that works for you.

If you have any further questions, feel free to send us an email.