SST v3 Apps skill for Codex

SST v3 defines infrastructure in TypeScript in sst.config.ts, runs on Pulumi and Terraform providers (not CloudFormation or CDK), and keeps state in your own account. A well-run SST app has production protected from removal, one stage per developer, every resource reached through link instead of hardcoded names, and secrets set with sst secret rather than in .env files.

Inspect first

1. Read AGENTS.md, sst.config.ts, package.json and the sst version. v2 projects use sst.config.ts with stacks and CDK constructs; v3 uses $config with app() and run(). Do not mix their docs.
2. Check .sst/ is gitignored and sst-env.d.ts exists (generated types for links).
3. Find which AWS profile or credentials each stage uses (providers.aws.profile).
4. sst deploy, sst dev and sst secret need network and cloud credentials. In an offline sandbox, edit config and code, run tsc, and hand deploy commands to the user.

Config skeleton

/// <reference path="./.sst/platform/config.d.ts" />
export default $config({
  app(input) {
    return {
      name: "acme",
      home: "aws",
      removal: input?.stage === "production" ? "retain" : "remove",
      protect: ["production"].includes(input?.stage),
      providers: { aws: { region: "us-east-1" } },
    };
  },
  async run() {
    const vpc = new sst.aws.Vpc("Vpc", { bastion: false });
    const db = new sst.aws.Postgres("Db", { vpc });
    const uploads = new sst.aws.Bucket("Uploads");
    const stripeKey = new sst.Secret("StripeSecretKey");

    const api = new sst.aws.Function("Api", {
      handler: "packages/functions/src/api.handler",
      url: true,
      link: [db, uploads, stripeKey],
      vpc,
    });

    new sst.aws.Cron("Nightly", {
      schedule: "cron(0 4 * * ? *)",
      function: { handler: "packages/functions/src/nightly.handler", link: [db] },
    });

    const web = new sst.aws.Nextjs("Web", {
      path: "packages/web",
      link: [api, uploads],
      domain: $app.stage === "production" ? "app.example.com" : undefined,
    });

    return { api: api.url, web: web.url };
  },
});

Rules for app():

• removal: "retain" on production keeps buckets and databases if the stage is removed.
• protect: true blocks sst remove for that stage entirely. Set it for production.
• Do not import packages at the top of sst.config.ts; use dynamic await import() inside run() if you need one.

Linking instead of env vars

link grants IAM permissions and exposes typed values at runtime:

import { Resource } from "sst";
import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";

const s3 = new S3Client({});
export async function handler() {
  await s3.send(new PutObjectCommand({ Bucket: Resource.Uploads.name, Key: "x.txt", Body: "hi" }));
  const key = Resource.StripeSecretKey.value;
  const { host, port, username, password, database } = Resource.Db;
  // ...
}

Resource.X is undefined when the resource is not in that function’s link array, or when the code runs outside SST (plain node). Run scripts with sst shell -- <cmd> to get links locally.

Secrets

npx sst secret set StripeSecretKey sk_test_xxx            # current stage
npx sst secret set StripeSecretKey "$PROD_KEY" --stage production   # confirm with user
npx sst secret list --stage production
npx sst secret set StripeSecretKey sk_test_xxx --fallback # default for all dev stages

Secrets are encrypted in the state bucket and injected through links. A secret declared in config but never set fails the deploy with a clear error; set it before deploying.

Daily commands

npx sst dev                        # personal stage; live functions, runs frontends in a multiplexer
npx sst deploy --stage staging
npx sst diff --stage production    # preview changes before a production deploy
npx sst deploy --stage production  # only after the user approves the diff
npx sst remove --stage pr-123      # tear down a preview stage
npx sst unlock --stage staging     # after an interrupted deploy left a lock
npx sst refresh --stage staging    # reconcile state with what exists in the cloud

Stage naming: default stage is your local username, so each developer gets an isolated copy. Use pr-<number> for previews and remove them when the PR closes.

Component decision table

Need	Component
Next.js, Astro, Remix, SvelteKit, Nuxt, SolidStart	sst.aws.Nextjs, sst.aws.Astro, … (OpenNext and adapters under the hood)
Static SPA	sst.aws.StaticSite
HTTP API in Lambda	sst.aws.Function with url: true, or sst.aws.ApiGatewayV2 for routes and auth
Long-running container service	sst.aws.Cluster plus sst.aws.Service (ECS Fargate) in a Vpc
Queue and consumer	sst.aws.Queue with .subscribe()
Postgres	sst.aws.Postgres (RDS) or sst.aws.Aurora; both need a Vpc
Path routing across several apps under one domain	sst.aws.Router
Cloudflare Worker, KV, D1	sst.cloudflare.Worker and related components, with home: "cloudflare" or a cloudflare provider
Anything without a component	Use the Pulumi provider directly (aws.s3.BucketPolicy, etc.) inside run()

Customize the underlying resources with transform rather than forking a component:

new sst.aws.Bucket("Uploads", {
  transform: { bucket: (args) => { args.forceDestroy = $app.stage !== "production"; } },
});

Verification

• npx tsc --noEmit passes with the generated sst-env.d.ts.
• npx sst diff --stage <stage> shows only intended creates and updates; no replacements of databases or buckets unless planned.
• After deploy, outputs (URLs) respond; a linked resource read works in logs.
• Production stage has protect and removal: "retain".
• Preview stages are removed after merge (CI job or manual sst remove).

Gotchas

• Renaming a component’s logical name (the first argument) replaces the resource; for a database or bucket that means data loss. Keep names stable.
• sst dev deploys real infrastructure to your personal stage; it costs money while running and leaves resources until you sst remove it.
• Functions in a VPC need a NAT gateway or VPC endpoints to reach the internet and AWS APIs; sst.aws.Vpc has a nat option, and NAT gateways are a fixed monthly cost.
• Interrupted deploys leave a lock in the state; sst unlock is safe only when no other deploy is actually running.
• Upgrading SST changes the bundled provider versions; run sst diff after every upgrade.