SSM (Parameter Store)

Lightweight, dependency-free fake of AWS Systems Manager (SSM) Parameter Store that speaks the real AWS JSON 1.1 wire protocol, so application code using @aws-sdk/client-ssm can run against it with zero cost and zero side effects.

Quick Start

Start the server:

import { SsmServer } from "./services/ssm/src/server.js";

const server = new SsmServer(4578);
await server.start();
// ... use it ...
await server.stop();

Connect with the real AWS SDK client:

import {
  SSMClient,
  PutParameterCommand,
  GetParameterCommand,
  GetParametersByPathCommand,
} from "@aws-sdk/client-ssm";

const ssm = new SSMClient({
  region: "us-east-1",
  endpoint: "http://127.0.0.1:4578",
  credentials: { accessKeyId: "parlel", secretAccessKey: "parlel" },
});

// Write a parameter
await ssm.send(
  new PutParameterCommand({ Name: "/app/db/host", Value: "localhost", Type: "String" }),
);

// Write a secret
await ssm.send(
  new PutParameterCommand({ Name: "/app/db/password", Value: "s3cr3t", Type: "SecureString" }),
);

// Read it back
const { Parameter } = await ssm.send(new GetParameterCommand({ Name: "/app/db/host" }));
console.log(Parameter.Value); // "localhost"

// Fetch a whole hierarchy
const tree = await ssm.send(
  new GetParametersByPathCommand({ Path: "/app", Recursive: true }),
);
console.log(tree.Parameters.map((p) => p.Name));

Configuration via environment variables

The @aws-sdk/client-ssm client honors these, set them to point the SDK at the fake:

AWS_ACCESS_KEY_ID=parlel
AWS_SECRET_ACCESS_KEY=parlel
AWS_REGION=us-east-1
AWS_ENDPOINT_URL_SSM=http://127.0.0.1:4578
AWS_ENDPOINT_URL=http://127.0.0.1:4578

Implemented operations

Parameter CRUD

• PutParameter — create/overwrite; versions auto-increment; supports String, StringList, SecureString; Tier (Standard / Advanced / Intelligent-Tiering); AllowedPattern, Description, DataType, KeyId, Tags (on create only).
• GetParameter — by name, by name:version, or name:label selector; WithDecryption accepted (no-op).
• GetParameters — batch (max 10); returns Parameters + InvalidParameters.
• GetParametersByPath — hierarchical fetch, Recursive, ParameterFilters, pagination.
• DeleteParameter
• DeleteParameters — batch; returns DeletedParameters + InvalidParameters.
• DescribeParameters — metadata only (no values), legacy Filters + modern ParameterFilters, pagination.
• GetParameterHistory — all versions with labels, in order, pagination.

Version labels

• LabelParameterVersion — attach labels to a version (labels auto-move between versions); validates label rules; returns InvalidLabels.
• UnlabelParameterVersion — detach labels; returns RemovedLabels + InvalidLabels.

Tagging

• AddTagsToResource
• RemoveTagsFromResource
• ListTagsForResource

Resource policies

• PutResourcePolicy
• GetResourcePolicies
• DeleteResourcePolicy

Service settings

• GetServiceSetting
• UpdateServiceSetting
• ResetServiceSetting

Parlel internal (not part of SSM)

• GET /_parlel/health — { status, service, parameters }
• POST /_parlel/reset — clears all in-memory state

Surface coverage

This emulator faithfully replicates the API surface most application code and agents exercise. Anything below the supported lines is either an intentional design choice for a fast, zero-cost local emulator (✓ By design) or a candidate for a future release (⟳ Roadmap) — never a silent inaccuracy.

Legend: ✅ fully supported · ◐ accepted (stored, not strictly enforced) · ✓ by design · ⟳ on the roadmap.

Error codes / shapes

Errors are returned with a non-2xx HTTP status and an AWS JSON 1.1 body:

{ "__type": "ParameterNotFound", "message": "Systems Manager could not find the parameter /missing." }

The x-amzn-errortype response header carries the same code. The @aws-sdk/client-ssm client maps __type to error.name.

Notes on fidelity

• Timestamps are serialized as epoch-second numbers, matching the AWS JSON 1.1 wire format the SDK expects.
• Parameter names may be flat (my-param) or hierarchical (/a/b/c). Names beginning with the reserved aws/ssm prefixes are rejected, matching AWS.
• SecureString values are stored as-is (no KMS). This keeps the fake dependency-free; WithDecryption: true simply returns the stored value.
• Standard tier caps values at 4096 bytes; Advanced at 8192 bytes. Intelligent-Tiering is promoted to Advanced when the value exceeds the standard limit or Policies are present.

Configuration — test.env

Copy these into your test.env (used by the bridge sidecar flow). Tokens are Parlel's seeded test credentials — any non-empty value is accepted by the emulator, so you rarely need to change them. Swap in real credentials only when pointing at the live service in prod.env.

AWS_ACCESS_KEY_ID=parlel
AWS_SECRET_ACCESS_KEY=parlel
AWS_REGION=us-east-1
AWS_ENDPOINT_URL_SSM=http://parlel-bridge:4578
AWS_ENDPOINT_URL=http://parlel-bridge:4578