---

ServerlessInsight (si) is an open-source, cross-cloud serverless framework. Instead of juggling provider-specific CLIs, console clicks and one-off scripts, you describe the whole serverless stack — functions, HTTP endpoints, object storage, databases and tables — in a single YAML file, then let si plan, deploy and operate it.

Think Terraform for serverless: one declarative workflow with state tracking and drift detection, built around functions, API gateways and serverless data services. No vendor lock-in, Apache-2.0 licensed.

Deployable today: Alibaba Cloud, Tencent Cloud and Volcengine. Huawei Cloud, AWS, Azure and Google Cloud are on the roadmap.

Table of contents

• Quick start
• Why ServerlessInsight
• Features
• Supported providers
• Documentation
• Roadmap
• Architecture
• Development
• Community
• Contributing
• Sponsor
• License

Quick start

Requires Node.js 22.12 or later.

npm install -g @geek-fun/serverlessinsight
si --version

Create serverlessinsight.yml:

version: 0.0.1

provider:
  name: aliyun
  region: cn-hongkong

app: hello-world
service: hello-world-api

functions:
  hello_function:
    name: hello-world-fn
    code:
      runtime: nodejs18
      handler: index.handler
      path: ./src
    memory: 512
    timeout: 10

events:
  api_gateway:
    type: API_GATEWAY
    name: my-api-gateway
    triggers:
      - method: GET
        path: /api/hello
        backend: ${functions.hello_function}

Then:

si validate                 # check the config against the IaC schema
si diff                     # show what would change, without saving state
si deploy --stage prod      # show the plan, confirm, and apply
si local                    # run the app locally on http://localhost:4567
si destroy --stage prod     # remove everything si created

si discovers serverlessinsight.yml in the current directory; pass -f <path> for a different file name. To target another cloud, select -v tencent or -v volcengine with a valid region and a compatible resource configuration. The override selects an independent deployment; adapt unsupported runtimes or resources before deploying.

Why ServerlessInsight

• Serverless-native, not generic IaC. Functions, triggers, API gateways, domains, buckets, databases and tables are first-class resources with provider-aware defaults — no hand-written Terraform modules or SDK wrapper scripts.
• One configuration format across clouds. Reuse supported primitives and stage variables across providers; validate each target configuration before deploying.
• Plan before anything happens. si diff reads state and live resources without writing anything; si deploy executes exactly the plan you approved, and manual console changes surface as drift.
• Built for automation. Logs go to stderr and machine-readable results to stdout, every JSON envelope is versioned, error codes are stable across locales, and exit codes follow Terraform conventions.
• Real local development. Run your handlers, HTTP routes, timer schedules and bucket endpoints locally with the same configuration — no cloud account or credentials needed.
• Open source, no lock-in. Apache-2.0, state in a local file or your own bucket, and no proprietary runtime to adopt.

Features

Multi-cloud, one config

Use one configuration format across Alibaba Cloud, Tencent Cloud and Volcengine. Shared mappings handle supported provider differences; each target must support the declared runtimes and resources.

• Unified configuration — one serverlessinsight.yml format for every provider
• Provider-specific mapping — runtime names, trigger shapes and resource types are translated to native values
• Cross-provider validation — unsupported target resources fail before cloud execution

Plan before deploy

si diff previews every change on Alibaba Cloud, Tencent Cloud and Volcengine. It reads the configured state backend and live cloud resources without applying changes or saving state.

si diff --stage dev
si diff --stage dev --json
si diff --stage dev --region cn-beijing -p memory=1024
si diff --stage dev --no-refresh

Use -p, --parameter <key=value> repeatedly to override configuration variables. --no-refresh skips live drift checks for tracked resources; ownership probes for new resources still run. Credentials and the selected state backend must be configured. Read failures exit with an error. Migrated legacy state produces a warning and remains unchanged.

Volcengine plans include functions, TOS buckets and API Gateway resources in dependency order.

Exit codes: si diff exits 0 when there are no changes, 2 when changes are present (Terraform convention), and 1 on errors. si validate exits 0 when valid and 1 when validation fails.

Independent provider and region deployments

Deployment identity is Org / App / Service / Stage / Provider / Region. app and service stay literal in YAML; -s, -v and -r select one deployment. A compatible YAML can be reused, or separate YAML files can describe different regional resources. Selecting the same scope and backend location addresses the same deployment. Changing provider/region creates or updates the selected deployment and preserves the previous deployment until an explicitly scoped destroy. Provider-specific declarations must be supported by the target cloud; overrides do not translate unsupported resources.

Local state stays at .serverlessinsight/state-<app>-<service>.json; Bucket Store keeps the exact configured key. Both store a V4 aggregate partitioned by stage/provider/region under one whole-file lock. Executors and SaaS snapshots use a single-deployment V4 view; SaaS mutations require scope protocol 3. Cloud accounts remain credential context rather than another identity dimension.

See deployment state and migration for storage credentials, automatic V3 upgrades, ownership handoff, lock behavior and recovery.

State backends

backend.state_manager.type: BUCKET_STORE keeps the exact configured key in your own bucket. Every integrated workload provider has a native state backend; -v and -r workload overrides never redirect state storage.

Workload provider	State storage	Explicit selection	Credentials
aliyun	OSS	storageProvider: aliyun	ALIYUN_ACCESS_KEY_ID / ALIYUN_ACCESS_KEY_SECRET
tencent	COS	storageProvider: tencent	TENCENTCLOUD_SECRET_ID / TENCENTCLOUD_SECRET_KEY
volcengine	TOS	storageProvider: volcengine	VOLCENGINE_ACCESS_KEY_ID / VOLCENGINE_SECRET_KEY

version: 0.0.1
app: example
service: api
provider:
  name: volcengine
  region: cn-beijing
backend:
  state_manager:
    type: BUCKET_STORE
    bucket: example-state
    key: infra/state.json

Permanent and temporary (STS) credentials work for all three backends; storage credentials are resolved for the storage cloud and never reused from another cloud. Unsupported storage providers are rejected explicitly. TOS uses HTTPS with the configured storageRegion and bounded timeouts. Grant read/write/delete on the state key and its .backup, .si-lock and upgrade siblings; bucket versioning permissions are not required. See the backend matrix, TOS setup and required permissions.

Bucket Store locks are best-effort, not atomic: serialize all writers sharing one bucket/key, including different stages, providers and regions. See the known concurrency limitation. Local and SaaS locking are unchanged.

Infrastructure as code

Declarative YAML with validation, planning and state management, following proven IaC patterns.

• State tracking — incremental deployments from .serverlessinsight/ state, with local, bucket and SaaS backends
• Drift detection — resources changed outside si are flagged before the next deploy
• Validation — type-safe template validation catches config errors before they reach the cloud
• Partial failure recovery — successfully deployed resources are saved even when others fail; retry to continue
• State locking — automatic locking with si force-unlock for recovery; Bucket Store uses best-effort coordination and requires serialized writers

Built for agents and scripts

The CLI is designed to be driven by agents and shell scripts: logs always go to stderr while result data goes to stdout, so piping stdout into jq always yields a single parseable JSON document.

si diff --json | jq '.summary'
si validate --json | jq '.valid'
si show --json | jq '.resourceCount'
si schema | jq '."$id"'   # self-contained draft-07 JSON Schema of the IaC format

Stable output envelopes, error codes and color behavior

Stable output envelopes (each carries a version field, so shapes only ever change under a new version):

• si diff --json → { planVersion: 2, provider, app, service, stage, region, changes: [{ logicalId, type, action: "create|update|destroy|recreate", attributes, drifted?, driftReasons? }], summary: { create, update, destroy, recreate, unchanged } }
• si validate --json → { validateVersion: 1, valid, errors: [{ path, keyword, message, allowedValues? }] }
• si show --json → { showVersion: 2, provider, app, service, stage, region, stateLocation, backend: "saas|bucket_store|local", locked, lock, resources, resourceCount, ... }
• failures (in --json mode) → { error: { code, message } } on stdout

Stable error codes: error codes are the i18n message keys behind the translated message (e.g. RAM_ROLE_NOT_FOUND_IN_CLOUD) — they are identical under every locale, so agents can map codes to self-healing actions regardless of LANG.

Colors: ANSI color is disabled when the NO_COLOR environment variable is set (no-color.org) or --no-color is passed, keeping piped output clean in non-TTY environments.

Local development

Run and debug serverless functions locally without deploying to the cloud or configuring credentials.

• HTTP functions — provider-native event, context and response translation for Aliyun FC, Tencent SCF function URLs and Volcengine veFaaS
• Timer triggers — functions.*.triggers.timer schedules fire against UTC wall-clock and invoke your handler with the provider's timer event shape
• Bucket file serving — access local storage files over HTTP for rapid iteration
• Watch mode — code changes reload automatically
• Same config, different target — si local -s dev reuses your existing configuration

See Local development for the supported subset and runnable examples: Tencent SCF and Volcengine veFaaS.

API gateway & custom domains

Configure HTTP endpoints and bind custom domains with automatic DNS verification.

• HTTP triggers — define triggers with HTTP methods and paths, backed by a function
• Custom domains — automatic CNAME + DNS TXT ownership verification for OSS and API Gateway on Alibaba Cloud, and DNSPod-backed domains on Tencent Cloud
• CDN acceleration — edge caching and global content delivery for bucket domains on Alibaba Cloud and Tencent COS (see the capability matrix)
• OSS transfer acceleration — cross-region data transfers through the Alibaba backbone
• Tencent function URLs — HTTP entry points without a standalone gateway resource
• Function custom domains — per-function domains binding list with cross-function path-merged routes, certificates (certificate_id or inline PEM) and a public function-URL precondition on Alibaba Cloud and Tencent Cloud (see the binding guide)

Timer triggers

Schedule functions with a provider-agnostic si-cron expression under functions.*.triggers.timer:

functions:
  my_fn:
    triggers:
      timer:
        - name: billing-run            # required — drift detection is name-keyed
          cron: '0 23 3 * * *'         # required — si-cron, interpreted in UTC
          payload: '{"job":"billing-run"}'  # optional, passed through verbatim
          enable: true                 # optional, default true
          description: daily billing   # optional
        - name: report-hourly
          cron: '@every 1h'

cron accepts a standard 5-field expression (minute hour day month weekday), a 6-field expression with a seconds prefix, or @every <duration> (30s, 5m, 1h, 1d, …). si-cron is always UTC — the synthesis layer translates it into each provider's dialect (Aliyun FC3 6-field, Tencent SCF 7-field with year, Volcengine veFaaS 5-field crontab), including the UTC+8 field shift, so the same YAML fires at the same instant everywhere. Invalid expressions and provider capability limits (Tencent SCF allows at most 10 timers per function) fail at si validate, before any deploy.

triggers vs top-level events

functions.*.triggers (http, timer) are things that invoke this function — they are function-owned, die with the function, and have no independent configuration surface. Top-level events (e.g. API_GATEWAY) are infrastructure resources with their own config face — custom domains, certificates, route tables — that keep living when a backend function is removed. Rule of thumb: independent configuration surface → events; pure scheduling/event binding → triggers.

Resource management

Beyond functions — manage the full serverless stack, including storage, databases and tables.

• Object storage — OSS (Alibaba), COS (Tencent), TOS (Volcengine)
• Databases — RDS MySQL Serverless, TDSQL-C and Elasticsearch Serverless
• Tables — TableStore on Alibaba Cloud
• GPU functions — deploy GPU-enabled serverless functions on Alibaba Cloud

Supported providers

Provider	Functions	HTTP entry	Object storage	Databases & tables	State backend	Status
Alibaba Cloud	✅ FC3	✅ API Gateway	✅ OSS	✅ RDS MySQL Serverless, TableStore, Elasticsearch Serverless	✅ OSS	Stable
Tencent Cloud	✅ SCF	✅ Function URL triggers	✅ COS	✅ TDSQL-C, Elasticsearch Serverless	✅ COS	Stable
Volcengine	✅ veFaaS	✅ API Gateway	✅ TOS	—	✅ TOS	Stable
Huawei Cloud	⚠️ Terraform template only	—	—	—	—	Preview
AWS	—	—	—	—	—	Planned
Azure	—	—	—	—	—	Planned
Google Cloud	—	—	—	—	—	Planned

Notes:

• Huawei Cloud configuration is parsed and can generate Terraform HCL templates, but deployment is not implemented yet.
• Tencent Cloud has no standalone API Gateway resource; HTTP entry points use function URL triggers.
• Volcengine does not yet support serverless databases or tables.
• Bucket Store state is native on OSS/COS/TOS. Other providers have no state backend and are rejected explicitly.
• See the full provider matrix for resource-level details.

Documentation

Resource	Link
Getting started	https://serverlessinsight.com/getting-started.html
Configuration reference	https://serverlessinsight.com/reference.html
CLI reference	https://serverlessinsight.com/cli.html
JSON Schema	si schema (self-contained draft-07)
Local development	docs/local-development.md
Deployment state	docs/regional-deployment-state.md
State locking	docs/state-locking.md
Architecture decisions	docs/adr
Samples	samples
Changelog	CHANGELOG.md
FAQ	https://serverlessinsight.com/faq.html

Roadmap

• Huawei Cloud function deployment (template generation exists today)
• AWS, Azure and Google Cloud providers
• Tencent Cloud standalone API Gateway resources
• Volcengine serverless databases and tables
• More serverless resources and provider capabilities

Roadmap items are directional, not commitments. Open an issue to discuss priorities.

Architecture

ServerlessInsight follows a functional client architecture that cleanly separates cloud provider SDKs from business logic:

┌─────────────────────────────────────────┐
│   Resource / Planner / Executor Layer   │  ← Provider-agnostic business logic
│   (Pure functions, no SDK imports)       │
└─────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────┐
│         Functional Client Layer          │  ← Encapsulated SDK operations
│ (aliyunClient, tencentClient,           │
│  volcengineClient)                       │
└─────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────┐
│      Cloud Provider SDKs                 │  ← @alicloud/*, tencentcloud-*, @volcengine/*
└─────────────────────────────────────────┘

• Functional and pure — business logic uses pure functions with immutable data
• SDK encapsulation — provider SDKs are accessed only through client modules
• Functional-first — type over interface, functions over classes, declarative collection handling

Development

ServerlessInsight is built with Node.js + TypeScript, Commander.js for the CLI, and a functional architecture.

Prerequisites

• Node.js >= 22.12
• npm (bundled with Node.js)

Build from source

git clone https://github.com/geek-fun/serverlessinsight.git
cd serverlessinsight
npm install
npm run build
npm link

Scripts

Command	Description
npm run build	TypeScript compilation
npm test	All tests with coverage
npm run test:unit	Unit tests only
npm run test:service	Service tests only
npm run test:ci	CI test run
npm run lint:check	ESLint check
npm run lint:fix	Auto-fix lint issues

Tests are split into fast, fully mocked unit tests and service tests that exercise the real parser, planner, executor and state manager. Coverage is enforced at 85% for branches, functions, lines and statements.

Project structure

src/
├── commands/        # CLI command handlers (deploy, destroy, diff, local, ...)
├── common/          # Shared utilities, clients, state and lock management
│   ├── aliyunClient/
│   ├── tencentClient/
│   └── volcengineClient/
├── lang/            # i18n translations (en.ts, zh-CN.ts)
├── parser/          # YAML parsing and validation
├── stack/           # Provider-specific resource logic
│   ├── aliyunStack/
│   ├── scfStack/            # Tencent Cloud
│   ├── volcengineStack/
│   ├── localStack/          # Local development server
│   └── rfsStack/            # Huawei Cloud Terraform templates (preview)
├── types/           # TypeScript type definitions
└── validator/       # JSON Schema validation
tests/
├── fixtures/        # Test fixtures (YAML configs, artifacts)
├── unit/            # Isolated unit tests
└── service/         # End-to-end service tests

See AGENTS.md for coding conventions, test rules and architecture principles.

Community

       

Contributing

Contributions are welcome — bug reports, feature requests, documentation fixes and code.

• Open an issue with the bug report or feature request template.
• Before opening a pull request, run npm run lint:check, npm run build and npm test.
• Follow the conventions in AGENTS.md and the existing pull request template.

Sponsor

     

License

Apache 2.0 © GEEKFUN