Skip to content

Lambda

Protocol: REST JSON Endpoint: http://localhost:4566/2015-03-31/functions/...

Floci Lambda runs your function code locally inside real Docker containers - close enough as AWS Lambda does (using Firecracker micro VM).

Supported Operations

Operation Description
CreateFunction Deploy a Lambda function
GetFunction Get function details and download URL
GetFunctionConfiguration Get runtime configuration
ListFunctions List all functions
UpdateFunctionCode Upload new code
UpdateFunctionConfiguration Update runtime, handler, memory, timeout, environment, architectures, tracing, layers, and more
DeleteFunction Remove a function
Invoke Invoke a function synchronously or asynchronously. A durable function starts a durable execution
CreateEventSourceMapping Connect SQS / Kinesis / DynamoDB Streams to a function
GetEventSourceMapping Get event source mapping details
ListEventSourceMappings List all event source mappings
UpdateEventSourceMapping Update a mapping
DeleteEventSourceMapping Remove a mapping
PublishVersion Publish an immutable version
ListVersionsByFunction List all published versions of a function, $LATEST first and then published versions in ascending numeric order
CreateAlias Create a named alias pointing to a version
GetAlias Get alias details
ListAliases List all aliases for a function
UpdateAlias Update an alias
DeleteAlias Delete an alias
AddPermission Add a resource-policy statement
GetPolicy Get the function resource policy
RemovePermission Remove a resource-policy statement
GetFunctionCodeSigningConfig Return the code-signing config attached to $LATEST (or an empty ARN)
PutFunctionCodeSigningConfig Attach or replace a code-signing config on $LATEST
DeleteFunctionCodeSigningConfig Detach the code-signing config from $LATEST
ListFunctionsByCodeSigningConfig List functions carrying a config, with marker pagination
CreateCodeSigningConfig Create a code signing configuration
GetCodeSigningConfig Read a code signing configuration
UpdateCodeSigningConfig Update the members the request names
DeleteCodeSigningConfig Delete a code signing configuration
ListCodeSigningConfigs List the configurations in the region
CreateFunctionUrlConfig Provision a function URL
GetFunctionUrlConfig Read function URL config
ListFunctionUrlConfigs List a function's URL configurations across its unpublished version and aliases, with marker pagination
UpdateFunctionUrlConfig Update function URL config
DeleteFunctionUrlConfig Delete function URL config
ListTags List tags on a function or event source mapping
TagResource Tag a function or event source mapping
UntagResource Untag a function or event source mapping
PutFunctionConcurrency Set reserved concurrent executions
GetFunctionConcurrency Get reserved concurrent executions
DeleteFunctionConcurrency Clear reserved concurrent executions
PutProvisionedConcurrencyConfig Initialize Docker environments for a published version or simple alias
GetProvisionedConcurrencyConfig Read the allocation's actual initialization status and capacity
ListProvisionedConcurrencyConfigs List configured versions and aliases with their current capacity
DeleteProvisionedConcurrencyConfig Remove an allocation and stop its environments
GetAccountSettings Account limits plus usage derived from the caller's stored functions
PutFunctionEventInvokeConfig Set the asynchronous invocation settings of a function, version or alias (retries, event age, destinations)
UpdateFunctionEventInvokeConfig Change some of those settings, leaving the rest as they are
GetFunctionEventInvokeConfig Read the asynchronous invocation settings
DeleteFunctionEventInvokeConfig Remove the asynchronous invocation settings
ListFunctionEventInvokeConfigs List the asynchronous invocation settings of every version and alias of a function
CheckpointDurableExecution Record the operation updates of the Durable Execution SDK and return the new state
GetDurableExecutionState Operations of a running durable execution, for replay
GetDurableExecution Status, result or error and the DurableConfig of a durable execution
GetDurableExecutionHistory Event log of a durable execution, oldest or newest first
ListDurableExecutionsByFunction Durable executions of a function or version, filtered by status, name and start time
StopDurableExecution Stop a running durable execution with an error
SendDurableExecutionCallbackSuccess Complete a durable callback with a result, up to 1 MB
SendDurableExecutionCallbackFailure Fail a durable callback with an error
SendDurableExecutionCallbackHeartbeat Keep a durable callback with a heartbeat timeout alive

UpdateFunctionConfiguration validates MemorySize and Timeout as whole numbers in their supported ranges before changing any stored settings. A rejected value returns InvalidParameterValueException and leaves the function configuration unchanged.

CreateFunction and UpdateFunctionConfiguration enforce the 4 KB environment-variable limit. The compact JSON Variables object must fit within 4,096 UTF-8 bytes, including keys, values, punctuation, and JSON escaping, as described in the AWS deployment guidance. An oversized environment returns HTTP 400 with InvalidParameterValueException before creating a function or changing any stored configuration. Omitting Environment on an update preserves the existing variables; an empty Variables object clears them. Validation stops serializing oversized input without allocating full JSON and UTF-8 copies. Quota errors include AWS's String measured: detail. The diagnostic retains up to 5,120 UTF-8 bytes of compact variables JSON; larger inputs end with ..., dropping any incomplete trailing UTF-8 character. This keeps diagnostic allocation and serialization bounded. CloudFormation omits unchanged environment variables during in-place configuration updates, so a function persisted before quota enforcement can retain an oversized environment when another property changes. Changing or removing its variables still updates the environment and enforces the quota.

The event invoke configuration is stored and returned as AWS does, and AWS::Lambda::EventInvokeConfig provisions it from a stack. A SAM function's EventInvokeConfig expands into that resource as sam deploy does: on $LATEST, or on the AutoPublishAlias alias, with the inline role policy for each destination and the SQS queue or SNS topic SAM creates when a destination gives only its Type. Asynchronous invocations apply its retry, event age, destination settings, and dead-letter queue configurations (DeadLetterConfig).

Deployment package storage

New Lambda deployment buckets are service-owned and do not appear in S3 ListBuckets, including paginated results. Deleting a function removes its package objects while retaining the shared regional bucket for other functions. Customer buckets with similar names remain visible. Existing persisted buckets without service-ownership metadata are not migrated or reclassified by name.

Creating a customer bucket with the exact name of an existing service-owned deployment bucket returns BucketAlreadyExists (HTTP 409), including in us-east-1. Ordinary customer buckets keep S3's default-region creation behavior, and Lambda can reuse its shared deployment bucket for subsequent functions.

Function policies under IAM enforcement

With IAM enforcement on, the statements AddPermission adds take part in authorizing calls to the function:

  • An invoke of a function named by a full or partial ARN runs the function in the account in the ARN. An invoke of another account's function needs its function policy to allow the caller as well as the caller's own identity policy.
  • A Step Functions Lambda task is authorized the same way, as the state machine's execution role or the role the task's Credentials name; see Step Functions.
  • GetFunction, GetFunctionConfiguration and ListDurableExecutionsByFunction, given a full ARN with a version or alias, read the function in the account in the ARN, and need its function policy to allow the caller in the same way.
  • Provisioned-concurrency configuration operations also act in the account named by the function reference. Cross-account access requires that function's policy to allow the caller.
  • Other operations act on the caller's own function of the name the ARN gives, whatever account the ARN names, and are authorized against both the function the ARN names and the caller's own function of that name. Floci does not serve them on another account's function, which AWS allows through a function policy.
  • Within one account, a statement naming the caller grants on its own. One naming only the account, as AddPermission --principal <account-id> writes it, delegates to the account, so the caller's identity policy has to allow the call too.
  • A version or alias written into the function name is part of the function an operation is authorized against, so a grant added with Qualifier covers a call naming that version or alias, and a grant on the function does not. Qualifier itself names a version or alias only for the provisioned-concurrency configuration operations, which act on it; every other operation is authorized against the function as its name gives it, as the Service Reference lists the function alone for those actions.
  • A statement conditioned on InvokedViaFunctionUrl does not admit a direct Invoke.
  • aws:PrincipalOrgID is in the request context for a caller whose account is in an organization, so a grant added with PrincipalOrgID admits the callers of that organization and no others. A caller in no organization carries no value for the key, and such a grant then admits none.

Qualified reads

GetFunction and GetFunctionConfiguration preserve an alias in the returned FunctionArn, while Version identifies that alias's primary published version. This applies to a Qualifier parameter and aliases embedded in a name, full ARN or partial ARN. Reading an alias does not change the stored version or the identities returned by subsequent unqualified and numeric-version reads.

Reserved Concurrency

Unqualified GetFunction reads include Concurrency.ReservedConcurrentExecutions when a reservation is set, including an explicit zero. Qualified reads omit Concurrency, whether $LATEST, a published version, or an alias is supplied through Qualifier or embedded in the function name or ARN. Use GetFunctionConcurrency to read the function-wide reservation separately. Deleting the reservation with DeleteFunctionConcurrency removes the Concurrency member from subsequent unqualified GetFunction responses.

Asynchronous Invocation Retries and Dead-Letter Queues

An asynchronous invocation (InvocationType: Event) answers 202 immediately and runs on the background pool. If the invocation fails, it is retried up to MaximumRetryAttempts (default: 2, total 3 attempts) unless the event age exceeds MaximumEventAgeInSeconds (default: 21600 seconds, 6 hours). As in AWS, the first retry waits one minute and the second two. FLOCI_SERVICES_LAMBDA_ASYNC_RETRY_DELAY_SECONDS sets the first wait (the second is twice it), and 0 retries back to back for fast local test runs. A wait never runs past MaximumEventAgeInSeconds, so an event that expires while waiting is reported then. A retry that finds the function's concurrency in use tries again every second until the event expires, where AWS backs off for up to five minutes. Deleting the function drops its pending retries without delivering a record, as AWS does.

When retries are exhausted or event age is exceeded:

  • If an OnFailure destination is configured, the failure record is delivered to the destination.
  • Otherwise, if a DeadLetterConfig (TargetArn) is configured on the function, the original request payload is delivered to the specified SQS queue or SNS topic with RequestID, ErrorCode (Number), and ErrorMessage (String, truncated to the first 1 KB) message attributes.
  • If both are configured, Floci routes to the OnFailure destination rather than the dead-letter queue by design choice (AWS describes dead-letter queues as an alternative to an on-failure destination without specifying precedence).

Asynchronous Invocation Destinations

An asynchronous invocation delivers its result to the OnSuccess or OnFailure destination the configuration names. Four of AWS's five destination kinds are supported, routed by the service in the destination ARN: an EventBridge event bus, an SQS queue, an SNS topic, and another Lambda function. A function with no destination configured is unaffected, and delivery never changes what the caller sees: the invoke still answers 202 immediately, and a destination that rejects the record is logged rather than reported back.

Every destination receives the same invocation record AWS sends:

{
  "version": "1.0",
  "timestamp": "2026-09-22T10:15:31.123Z",
  "requestContext": {
    "requestId": "8ea123e4-1db7-4aba-9559-05a9a25c8b78",
    "functionArn": "arn:aws:lambda:us-east-1:000000000000:function:bank-pawnshop:$LATEST",
    "condition": "Success",
    "approximateInvokeCount": 1
  },
  "requestPayload": { "bankId": "BANK-PawnShop" },
  "responseContext": { "statusCode": 200, "executedVersion": "$LATEST" },
  "responsePayload": { "bankId": "PawnShop", "rate": 3.5 }
}

On an EventBridge destination the record is the event detail, under the source lambda and the detail type Lambda Function Invocation Result - Success, so a rule can match a field of the function's own response at detail.responsePayload.<field>. A failed invocation carries the detail type Lambda Function Invocation Result - Failure, a condition of RetriesExhausted, a responseContext.functionError of Unhandled, and the error as its responsePayload. That functionError member is present only on a failure record. The approximateInvokeCount field reflects the actual number of attempts executed before completion or exhaustion.

An alias-specific destination configuration is used when the alias is invoked, whether the alias is named in Qualifier or on the function name. If the alias has none, Floci checks the configuration on the version that the alias resolves to.

Two limits are worth knowing:

  • An S3 OnFailure destination is not delivered. AWS added an S3 bucket as a fifth destination kind, on failure only. Floci routes on the service in the destination ARN and has no s3 arm, so such a record is dropped with a warning rather than written to the bucket. The configuration is still stored and read back, so Terraform and CloudFormation converge; only the delivery is missing.
  • A chain of Lambda destinations stops at 16 hops, but only a chain of Lambda destinations. A function whose OnSuccess names another function would otherwise invoke forever; AWS halts such a chain at about the same depth through recursive loop detection, and here the record at the sixteenth hop is dropped with a warning. The bound is keyed on the destination being a Lambda ARN, so a cycle that leaves and re-enters Lambda by another route is not bounded: a topic that fans back to the function, or a bus rule targeting it, each start a fresh chain at zero. Avoid configuring one until this is closed.

Durable Functions

A function created with DurableConfig is a durable function. Invoking it through a version or alias (name:1, name:live, ?Qualifier=1) starts a durable execution. An unqualified name is rejected, as on AWS. X-Amz-Durable-Execution-Name names the execution, and Floci generates a UUID when it is absent. X-Amz-Durable-Execution-Arn returns the execution ARN. A RequestResponse invoke blocks until the execution ends, waits included, and needs an ExecutionTimeout of 15 minutes or less. Event answers 202 and the execution continues in the background. Invocations through an ARN (EventBridge, Scheduler, function URLs, destinations) start durable executions the same way.

The checkpoint protocol under /2025-12-01 is the real one, so the Durable Execution SDK works unchanged for steps, waits, step retries, callbacks, chained invokes and replay. Timers are persisted and fired by a background sweep, so an execution survives a restart of Floci. A function that returns something other than the {Status, Result, Error} envelope fails its execution with Invalid Status in invocation output. A function that throws is re-invoked four more times, after 1, 2, 4 and 8 seconds, and then fails the execution with its error. AWS does the same over a few minutes.

The operations under a child context closed without ReplayChildren=true are left out of the invocation event and GetDurableExecutionState, as the API reference describes.

DeleteFunction of a durable function or one of its versions answers 202.

A callback (createCallback, waitForCallback) gets a callback id that the SendDurableExecutionCallback* APIs complete. Its TimeoutSeconds and HeartbeatTimeoutSeconds fail it with Callback.Timeout or Callback.Heartbeat, and each heartbeat restarts the heartbeat timeout. A failure sent with an empty request body fails the callback but does not invoke the function again, as on AWS, so the execution keeps waiting. The SDKs send {} when Error is omitted, which does invoke it.

A chained invoke (context.invoke) runs another function with an input of up to 1 MB. A durable target needs a version or alias and runs as its own durable execution, and its close completes the operation as SUCCEEDED, FAILED, TIMED_OUT or STOPPED. Any other function is invoked once, and an output over 1 MB fails the operation. A missing function or an unqualified durable one fails the operation at once, and a target in another account or Region is rejected at checkpoint. Stopping the parent leaves the child running, as on AWS.

Each durable execution gets an X-Ray trace header. It is built from the X-Amzn-Trace-Id header of Invoke when the request carries one. GetDurableExecution returns it as TraceHeader. Every invocation of the execution gets the same Root in _X_AMZN_TRACE_ID. A PassThrough function gets the Parent of the execution. When the header has none, the function gets only the Root if Sampled=1, and a new Parent on each invocation if Sampled=0. An Active function gets a new Parent on each invocation. A durable execution started by a chained invoke takes its header from ChainedInvokeOptions.XAmznTraceId, or from the calling execution when that is absent. A plain function invoked this way gets the same header.

GetDurableExecutionHistory leaves payloads out unless IncludeExecutionData=true is sent. The API reference names true as the default, but AWS answers this way.

SendDurableExecutionCallbackSuccess takes a result of up to 1 MB. The API reference names 256 KB, but AWS accepts 1 MB and rejects one byte more.

The public public.ecr.aws/lambda images do not bundle the SDK that the managed runtimes carry. Add aws-durable-execution-sdk-python or @aws/durable-execution-sdk-js to your deployment package.

Not emulated yet:

  • The execution role's lambda:InvokeFunction permission before a chained invoke. TenantId is recorded in the history only.
  • Durable executions started by Step Functions or by an event source mapping. These invoke the function as a plain one.
  • Payload encryption. KMSKeyArn is stored and returned only.
  • EventBridge status-change events and a dead-letter queue or destinations for durable executions.
  • The Lineage field AWS adds to the trace header.
  • The per-execution limits of 3,000 operations and 100 MB of persisted payload.
  • The Deleting state AWS shows for about a minute after DeleteFunction of a durable function. Floci removes it at once.

Code signing configuration pagination

ListCodeSigningConfigs accepts MaxItems from 1 to 10,000 and returns NextMarker when more configurations remain. Pass that value as Marker to continue listing. Omitting MaxItems returns up to 10,000 configurations. Markers are signed and scoped to the account and region; the final page omits NextMarker.

Hot-Reloading via Reactive S3 Sync

Floci supports automatic hot reload for S3 deployments as a local development convenience. AWS normally copies the deployment package: overwriting its S3 object alone does not redeploy the function.

When a Lambda function is created using an S3 bucket and key, Floci maintains a link between the function and its source object. Any subsequent update to that S3 object (e.g., via s3:PutObject) automatically triggers a reactive synchronization:

  1. Detection: Floci detects the S3 update via an internal event system.
  2. Synchronization: The new code is automatically re-extracted to the local code storage.
  3. Invalidation: Any active "warm" containers for that function are proactively drained.
  4. Reload: The very next invocation starts a fresh container with the updated code.

This allows you to update your Lambda code by simply re-uploading your ZIP to S3, without having to manually call UpdateFunctionCode or restart any containers.

Published versions retain their own code snapshots. Reactive sync updates only $LATEST; publication and extraction share the per-function lock so a version cannot capture a partial update.

Example

# 1. Create a function linked to S3
aws lambda create-function \
  --function-name my-function \
  --code S3Bucket=my-bucket,S3Key=function.zip \
  ...

# 2. Invoke (starts a warm container)
aws lambda invoke --function-name my-function out.json

# 3. Update the code in S3 (Triggers Reactive Sync)
aws s3 cp updated-function.zip s3://my-bucket/function.zip

# 4. Invoke again (automatically picks up the new code)
aws lambda invoke --function-name my-function out.json

Local development behavior

This mechanism requires no custom configuration or special strings. It uses standard AWS SDK and CLI calls; automatic redeployment after an S3 upload is a Floci convenience.

Configuration

Variable Default Description
FLOCI_SERVICES_LAMBDA_REACTIVE_S3_SYNC_ENABLED true Re-deploy a function when the S3 object it was deployed from is overwritten. false only stores the object, as AWS does
FLOCI_SERVICES_LAMBDA_REACTIVE_S3_SYNC_ASYNC false Re-deploy in the background, so the upload returns without waiting for it

By default the re-deploy runs inside the upload: PutObject, CopyObject or CompleteMultipartUpload returns only once the function has its new code. With FLOCI_SERVICES_LAMBDA_REACTIVE_S3_SYNC_ASYNC=true the upload returns at once, and the function reports LastUpdateStatus InProgress until the re-deploy finishes. Wait for it before invoking, or the invocation may still run the previous code:

aws s3 cp updated-function.zip s3://my-bucket/function.zip
aws lambda wait function-updated --function-name my-function
aws lambda invoke --function-name my-function out.json

Uploads that arrive while a re-deploy is running are coalesced: the next re-deploy reads the object as it is when it starts, so a burst of uploads costs at most one more. A re-deploy that fails, for example because the object is not a valid ZIP, leaves the previous code in place and reports LastUpdateStatus Failed with a LastUpdateStatusReason until the function's next successful update: a re-deploy, UpdateFunctionCode or UpdateFunctionConfiguration, since the status describes the last update of either kind. The status is kept in memory and is not persisted.

Hot-Reload via Bind Mount

For the tightest inner-loop development cycle, Floci supports a bind-mount hot-reload mode. Instead of packaging code into a ZIP and uploading it to S3, you point Floci directly at a directory on your host machine. The directory is bind-mounted read-only into /var/task inside the container, as /var/task is read-only in AWS Lambda, so every invocation runs the files as they currently exist on disk, with no upload or redeploy.

This is enabled by using the magic bucket name hot-reload when creating a function:

aws lambda create-function \
  --function-name my-function \
  --runtime nodejs22.x \
  --role arn:aws:iam::000000000000:role/lambda-role \
  --handler index.handler \
  --code S3Bucket=hot-reload,S3Key=/absolute/path/to/your/code \
  --endpoint-url http://localhost:4566

The S3Key must be an absolute path reachable by the Docker daemon. When Floci runs in Docker Compose, this is the path on the Docker host (the machine running Docker), not the path inside the Floci container.

How it works

  1. CreateFunction with S3Bucket=hot-reload marks the function as a hot-reload function; S3Key is stored as the host-side path.
  2. On each invocation, Floci starts a fresh ephemeral container with the host path bind-mounted at /var/task.
  3. The container executes the files as they exist at invocation time. Editing a file and immediately invoking picks up the change without any API call.
  4. After the invocation completes the container is stopped and removed, ensuring the next invocation always sees the current state of the directory.

Configuration

Hot-reload must be enabled explicitly. By default it is disabled so that S3Bucket=hot-reload is treated as a regular S3 bucket name.

FLOCI_SERVICES_LAMBDA_HOT_RELOAD_ENABLED=true

# Optional: restrict which host paths may be bind-mounted (comma-separated)
FLOCI_SERVICES_LAMBDA_HOT_RELOAD_ALLOWED_PATHS=/home/user/projects,/tmp

An S3Key is accepted when it is one of the listed directories or inside one. . and .. segments are resolved first, so /home/user/projects/../secrets and a sibling such as /home/user/projects-old are rejected. Symbolic links on the Docker host are not resolved by Floci. A path containing : is rejected. Without an allow-list any absolute host path is accepted except the host root, /var, /proc, and anything under /run or /var/run, where the Docker socket lives or can be reached. Floci logs a warning at startup when hot-reload is enabled without an allow-list.

Docker Compose setup: enable the feature and share the Docker socket:

services:
  floci:
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      FLOCI_SERVICES_LAMBDA_HOT_RELOAD_ENABLED: "true"

CloudFormation and SAM

AWS::Lambda::Function accepts the same pair. A template whose Code is {"S3Bucket": "hot-reload", "S3Key": "/absolute/path"} is handed to Lambda unchanged instead of being resolved against S3, so the stack creates a hot-reload function and reaches CREATE_COMPLETE. A SAM CodeUri of s3://hot-reload//absolute/path expands to the same Code: the double slash keeps the key absolute, because SAM takes everything after the first slash as the key. Redeploying the stack with an unchanged path is a no-op for the code; a changed path updates the function's bind mount through UpdateFunctionCode. Lambda's own hot-reload checks still apply, so a stack whose hot-reload path is relative, outside the allow-list, or used while hot-reload is disabled fails with Lambda's error as the resource status reason.

Limitations

  • The S3Key path is interpreted by the Docker daemon, not by Floci. When Floci itself runs inside Docker, the path must exist on the Docker host machine, not inside the Floci container.
  • Hot-reload containers are always ephemeral, so there is no warm-container reuse. Each invocation pays a cold-start penalty.
  • UpdateFunctionCode on a hot-reload function converts it back to a standard Zip function (the hot-reload bind-mount is removed).
  • S3 reactive sync is skipped for hot-reload functions because edits are picked up directly from disk.

Difference from Reactive S3 Sync

Reactive S3 Sync Bind-Mount Hot-Reload
Trigger Upload a new ZIP to S3 Edit files on disk
Cold start Only after upload Every invocation
Requires upload step Yes No
Works without hot-reload enabled Yes No
Path on host required No Yes

Concurrency enforcement

Reserved concurrency is enforced function-wide: invocations of every version and alias count against the function's reservation, and invocations beyond the reserved value return TooManyRequestsException (HTTP 429). Functions without a reserved value share a per-region pool. AWS Lambda's "account-level" limit is in fact a per-account-per-region quota, and Floci mirrors that by partitioning counters on the ARN's region segment. The pool size (default 1000) is configurable via floci.services.lambda.region-concurrency-limit and applies independently to each region. PutFunctionConcurrency validates that the requested value leaves at least floci.services.lambda.unreserved-concurrency-min (default 100) available for unreserved functions in that region.

Reducing or clearing a function's reserved value does not kill invocations that are already in flight. This matches AWS, which applies changes only to new invocations. As a consequence, during the drain window Σreserved-inflight + unreserved-inflight can briefly exceed region-concurrency-limit.

Function URLs are also reachable directly on /{proxy:.*} under the Lambda URL controller, which routes the request into the normal Invoke path.

ListFunctionUrlConfigs lists the unpublished function's URL and its alias URLs. It accepts MaxItems from 1 through 50, defaulting to 50, and resumes with Marker. Pagination uses Lambda's shared validation: out-of-range integers return ValidationException, non-integers return SerializationException, and an invalid marker returns InvalidParameterValueException with Invalid pagination key.. Missing or inaccessible function references return ResourceNotFoundException.

A function URL with InvokeMode: RESPONSE_STREAM streams the response: each chunk the handler writes reaches the caller as it is written. When the handler uses awslambda.HttpResponseStream.from, the status code, headers and cookies come from its prelude. Otherwise the response is a 200 with the content type the handler set, application/octet-stream by default. A function that fails before its stream starts, in its init or by timing out, answers 502. An error the handler throws ends the body where it stopped, an empty 200 if it wrote nothing: the runtime reports it in HTTP trailers, which Floci's runtime API does not read. A handler that does not stream is answered as with BUFFERED.

Function URLs are not available in AWS GovCloud (US) or in the China Regions (GovCloud guide, China guide), so CreateFunctionUrlConfig and ListFunctionUrlConfigs return InvalidParameterValueException in those regions, and an AWS::Lambda::Url in a CloudFormation stack there fails with it. See AWS Partitions.

Versions: CreateFunction and UpdateFunctionCode honour Publish, publishing a version and reporting it in the response's Version. The two differ in the ARN they return, matching the live service: CreateFunction keeps the unqualified FunctionArn while UpdateFunctionCode returns the qualified one (...:function:name:2), as PublishVersion does. Without Publish both answer for $LATEST and create nothing. UpdateFunctionConfiguration has no Publish parameter in the AWS API and none here.

On a cold launch, AWS_LAMBDA_FUNCTION_VERSION contains the executing version: $LATEST for an unqualified invocation and the published version number for a version or alias invocation. This follows the Lambda environment variable contract and was checked against live AWS in us-east-1 on October 12, 2026 at 19:49 UTC.

DeleteFunction honours Qualifier — it removes that published version only, leaving $LATEST, the other versions and the function's aliases in place; without a qualifier the whole function goes. Matching the live service, deleting $LATEST by qualifier and naming an alias are both rejected with InvalidParameterValueException, a version an alias points at is a ResourceConflictException, and a version that does not exist is a silent success rather than a 404.

Layers: PublishLayerVersion, GetLayerVersion, GetLayerVersionByArn, ListLayerVersions, ListLayers, and DeleteLayerVersion are implemented, with real local storage under {lambda.codePath}/layers/{name}/{version}. ListLayers and ListLayerVersions honour CompatibleRuntime, CompatibleArchitecture, MaxItems (1-50, defaulting to 50) and Marker, and always emit NextMarker, null on the last page. Under a filter, LatestMatchingVersion is the newest version that matches rather than the newest overall, and a layer with no matching version is omitted; a version published without CompatibleArchitectures matches neither architecture. Marker is opaque and signed with a key generated at startup, so a fabricated, edited or previous-run token is rejected with InvalidParameterValueException rather than applied as a cursor. One divergence: a parameter sent with an empty value (?CompatibleRuntime=) is treated as absent rather than rejected, because RESTEasy binds an empty query value as null. Resolution honours the ARN's account and partition: an ARN naming another account resolves to nothing rather than to a same-named layer of the caller's own, matching the live service, which answers that case with AccessDeniedException and never substitutes. CreateFunction/UpdateFunctionConfiguration validate each Layers ARN in the caller's own account eagerly against that storage, matching real AWS - an unresolvable one is rejected with InvalidParameterValueException: Layer version ... does not exist., not silently accepted.

DeleteLayerVersion accepts either a layer name or an unversioned layer ARN, with VersionNumber supplied separately. ARN deletion resolves the stored version in the ARN's region and removes its archive. IAM checks use that same layer-version ARN; another account's ARN cannot select a same-named layer in the caller's account.

An ARN naming another account or another partition is answered on the live service by the layer's resource policy: an AWS-managed public layer resolves, and everything else is AccessDeniedException. Measured on CreateFunction in ap-southeast-1, a foreign-account ARN and a cross-partition ARN return the same AccessDeniedException, so Floci returns that for both. Floci implements no layer permissions and cannot fetch real AWS content, so it cannot tell a public layer from a private one; refusing is the faithful default, being the answer AWS gives to every foreign ARN except a public one.

Set floci.services.lambda.accept-external-layer-arns: true (FLOCI_SERVICES_LAMBDA_ACCEPT_EXTERNAL_LAYER_ARNS) to record a same-partition foreign ARN on the function instead of refusing it, which is what a stack attaching Powertools, the AppConfig extension or a vendor-published layer needs. The trade is explicit: with it on, Floci also accepts an ARN AWS would refuse with AccessDeniedException, so a typo or a private third-party layer passes here and fails on deploy. The content is never mounted at /opt either way, and a warning is logged at attach time and again at invoke; publish your own copy of the content locally under a name you control if the handler needs it at runtime.

A layer ARN outside the caller's partition is refused whatever that setting says. Partitions are isolated, so no resource policy can ever make such a layer readable, and GetLayerVersionByArn rejects one outright with InvalidParameterValueException: Invalid layer version ....

Provisioned concurrency

Published versions with SnapStart.ApplyOn=PublishedVersions reject provisioned concurrency with ResourceConflictException, including through an alias. A configured alias cannot retarget to such a version. Eligibility uses the published snapshot, so changing $LATEST does not change older versions. Get and Delete retain their normal configuration lookup behavior, and unconfigured aliases can still point to SnapStart versions.

Put, Get and Delete use /2019-09-30/functions/{FunctionName}/provisioned-concurrency with a required Qualifier query parameter. Put accepts a positive integer ProvisionedConcurrentExecutions and returns HTTP 202 with IN_PROGRESS. An existing function without a configuration returns ProvisionedConcurrencyConfigNotFoundException from Get.

List uses the same route with List=ALL and no qualifier. It returns the function's configured versions and aliases, their qualified FunctionArn and current allocation status. An existing function without configurations returns an empty list. MaxItems accepts 1 through 50; NextMarker resumes with Marker. Markers are scoped to the function, account and region. Name, full ARN and partial ARN references use the same configuration inventory.

An alias and its resolved published version cannot both have configurations. Different aliases of the same provisioned version also conflict; other versions remain independent. LastModified uses Lambda's UTC +0000 form.

Each environment runs the real function initialization. READY requires the runtime and every discovered extension to send their first Runtime API Next request. Provisioning does not enqueue a handler event. Initialization failures become FAILED; the initialization deadline is the greater of 130 seconds and the configured function timeout. A later ordinary Invoke for that exact alias or version uses an available initialized environment, with on-demand spillover when all its environments are busy. Other aliases, versions, accounts and regions do not borrow that allocation.

Layer initialization uses the stored function's account and partition, including background workers without a request context. An unresolved configured layer or missing layer directory fails provisioned initialization; it is never silently omitted from a READY environment. Cross-account layer sharing remains unsupported.

With IAM enforcement enabled, these operations authorize the function owner and qualifier against the caller's identity policy and the owner's function policy. A cross-account grant for Get does not authorize Put, Delete, or another qualifier.

Provisioned environments are separate from ordinary idle eviction. Desired configurations are persisted; restarting Floci initializes new processes before reporting READY. Deleting the configuration, alias or function removes the owned environments. Changing an alias's version reinitializes its existing allocation for the new published version and releases the old version's configuration conflict. The alias retains its requested quota; retired environments retain their local container capacity until cleanup succeeds. An identical Put preserves the existing healthy allocation. Failed background alias refreshes retain their previous allocation and retry on later reconciliation without blocking other configurations. An alias with a configuration cannot move to $LATEST; remove the configuration first. Get and Delete remain available if the alias gains unsupported weighted routing.

This implementation supports the non-ephemeral Docker executor with immutable published versions and simple aliases. It refuses $LATEST, weighted aliases, hot reload, durable functions and other executors. Allocations share the configured warm-pool-max-per-function ceiling across a function's qualifiers, and the optional warm-pool-max-total ceiling across provisioned allocations. A function's reserved concurrency is also a ceiling. These local resource bounds do not implement AWS's complete regional provisioned-concurrency quota accounting, automatic scaling, or weighted-alias allocation. Provisioned runtimes receive their numeric AWS_LAMBDA_FUNCTION_VERSION and AWS_LAMBDA_INITIALIZATION_TYPE=provisioned-concurrency.

Configuration replacement and deletion remain committed if environment removal fails. Failed removals retain ownership and are retried while Floci is running; they continue to count against local container limits until cleanup succeeds.

Shutdown drains provisioned and on-demand containers concurrently within one floci.services.lambda.container-drain-timeout-seconds budget. The default is 15 seconds; set FLOCI_SERVICES_LAMBDA_CONTAINER_DRAIN_TIMEOUT_SECONDS when a larger fleet needs more time for Docker to finish removing stopped containers. Supported values are 1 through 300; invalid values fail initialization. The parent process's stop grace must exceed this budget. The destruction hook does not start another drain budget. Failed removals remain owned for a later retirement or reset retry; a completed removal is not repeated. A launch that outlasts the deadline is reported as incomplete cleanup. Its invocation is refused, and any returned container remains owned for a later cleanup retry; the deadline does not guarantee cancellation of an unresponsive container launcher.

If an invocation finishes after the shutdown deadline, releasing its still-owned container starts a separate bounded cleanup attempt. This does not extend the initial shutdown wait.

When using floci-cli, set floci stop --timeout <seconds> above the configured drain budget. The CLI currently defaults to 10 seconds, including for floci restart. For a longer drain, explicitly stop with the larger timeout and then start Floci.

Not Implemented

These AWS Lambda operations have no handler in Floci. Calls will return 404 or an error:

  • Layer permissions (AddLayerVersionPermission, RemoveLayerVersionPermission, GetLayerVersionPolicy)
  • InvokeWithResponseStream

Code signing enforcement is not emulated: an attached configuration never gates a deployment. The attachment lifecycle is supported for $LATEST: PutFunctionCodeSigningConfig attaches or replaces a configuration, GetFunctionCodeSigningConfig reads it, DeleteFunctionCodeSigningConfig detaches it, and ListFunctionsByCodeSigningConfig returns attached functions with marker pagination. PutFunctionCodeSigningConfig and the CodeSigningConfigArn supplied to CreateFunction return CodeSigningConfigNotFoundException when the named configuration does not exist. Configuration resource reads and ListFunctionsByCodeSigningConfig return ResourceNotFoundException for an unknown configuration. A malformed ARN or out-of-range MaxItems is rejected with InvalidParameterValueException first.

Configuration

Lambda container architecture

Floci uses the Docker host architecture by default. Set FLOCI_SERVICES_LAMBDA_HONOUR_ARCHITECTURES=true to run each function with its declared arm64 or x86_64 architecture. The Docker host must support the selected architecture. Foreign architectures require Docker Desktop or host emulation such as binfmt_misc with QEMU. Floci does not fall back to the host architecture when this setting is enabled.

Variable Default Description
FLOCI_SERVICES_LAMBDA_ENABLED true Enable or disable the service
FLOCI_SERVICES_LAMBDA_EPHEMERAL false Remove containers after each invocation
FLOCI_SERVICES_LAMBDA_RECONCILE_CONTAINERS_ON_STARTUP true Reclaim owned Docker containers from previous runs at startup and retry incomplete cleanup on cold starts; disable when deployments share the same owner identity
FLOCI_SERVICES_LAMBDA_HONOUR_ARCHITECTURES false Select each function's declared architecture for Docker image pulls and containers
FLOCI_SERVICES_LAMBDA_DEFAULT_MEMORY_MB 128 Default function memory (MB)
FLOCI_SERVICES_LAMBDA_DEFAULT_TIMEOUT_SECONDS 3 Default function timeout (seconds)
FLOCI_SERVICES_LAMBDA_DURABLE_SWEEP_ENABLED true Fire durable execution timers (waits, step retries, execution timeouts, retention expiry)
FLOCI_SERVICES_LAMBDA_DURABLE_SWEEP_INTERVAL_SECONDS 1 How often the durable sweep runs
FLOCI_SERVICES_LAMBDA_RUNTIME_API_BASE_PORT 12000 First port in the Lambda Runtime API range
FLOCI_SERVICES_LAMBDA_RUNTIME_API_MAX_PORT 12499 Last port in the Lambda Runtime API range. One port is held per running container, so the range width caps concurrent executions. Each running container also holds two streaming Docker connections plus one per extension, so a wider range needs a matching FLOCI_DOCKER_STREAMING_MAX_CONNECTIONS
FLOCI_SERVICES_LAMBDA_CODE_PATH ./data/lambda-code Directory where Lambda ZIP files are stored
FLOCI_SERVICES_LAMBDA_POLL_INTERVAL_MS 1000 Event-source mapping poll interval (milliseconds)
FLOCI_SERVICES_LAMBDA_ASYNC_RETRY_DELAY_SECONDS 60 Wait before the first retry of a failed asynchronous invocation (seconds); the second waits twice this, 0 retries back to back
FLOCI_SERVICES_LAMBDA_CONTAINER_IDLE_TIMEOUT_SECONDS 300 Idle container shutdown timeout (seconds)
FLOCI_SERVICES_LAMBDA_INIT_TIMEOUT_SECONDS 10 Time a newly started runtime has to finish its init and request its first invocation (seconds). A function whose Timeout plus 2 seconds is longer waits that long instead. See Slow cold starts
FLOCI_SERVICES_LAMBDA_WARM_POOL_MAX_PER_FUNCTION max(4, cpus) Maximum idle (warm) containers kept per function
FLOCI_SERVICES_LAMBDA_WARM_POOL_MAX_TOTAL 0 Maximum idle (warm) containers kept across all functions, LRU-evicted beyond it. 0 = unbounded. See the note below
FLOCI_SERVICES_LAMBDA_REGION_CONCURRENCY_LIMIT 1000 Maximum concurrent executions per region
FLOCI_SERVICES_LAMBDA_UNRESERVED_CONCURRENCY_MIN 100 Minimum unreserved capacity PutFunctionConcurrency must leave
FLOCI_SERVICES_LAMBDA_HOT_RELOAD_ENABLED false Enable bind-mount hot-reload via S3Bucket=hot-reload
FLOCI_SERVICES_LAMBDA_HOT_RELOAD_ALLOWED_PATHS (unset) Comma-separated allowlist of host paths that may be bind-mounted
FLOCI_SERVICES_LAMBDA_REACTIVE_S3_SYNC_ENABLED true Re-deploy a function when its S3 deployment object is overwritten. See Reactive S3 Sync
FLOCI_SERVICES_LAMBDA_REACTIVE_S3_SYNC_ASYNC false Run that re-deploy in the background so the upload does not wait for it
FLOCI_SERVICES_LAMBDA_DOCKER_NETWORK (unset) Docker network to attach Lambda containers to (overrides FLOCI_SERVICES_DOCKER_NETWORK)
FLOCI_SERVICES_LAMBDA_DOCKER_FLAGS (unset) Additional Docker flags applied to Lambda containers, including --env, --volume, --publish, --add-host, --dns, --label, --network, --user, --privileged, and --platform. Explicit --dns entries replace automatic embedded DNS and public fallback resolvers. Published ports support host:container and 127.0.0.1:host:container forms
FLOCI_SERVICES_LAMBDA_EXTRA_HOSTS (unset) Comma-separated hostname:ip entries added to each Lambda container's /etc/hosts; ip may be host-gateway, mirroring docker run --add-host
FLOCI_SERVICES_LAMBDA_DOCKER_HOST_OVERRIDE (unset) Explicit host/IP that spawned Lambda containers use to reach Floci's Runtime API, bypassing auto-detection
FLOCI_SERVICES_LAMBDA_CONTAINER_NAME_PREFIX floci Base name prefix for spawned Lambda containers and code volumes (e.g. acme → acme-<function>-<id> containers, acme-code-<function>-<hash> volumes; with FLOCI_DOCKER_RESOURCE_NAMESPACE set, the namespace follows the prefix and a short hash of it ends the volume name, e.g. acme-<namespace>-code-<function>-<hash>-<namespace hash>). Must be a valid Docker name segment ([A-Za-z0-9][A-Za-z0-9_.-]*); invalid values are ignored with a warning
FLOCI_SERVICES_LAMBDA_CODE_VOLUME_POPULATE_CONCURRENCY max(2, cpus/2) Maximum concurrent first-time code-volume populates. See the note below
FLOCI_SERVICES_LAMBDA_EXECUTOR docker Execution backend: docker (containers) or kubernetes (pods)
FLOCI_SERVICES_LAMBDA_KUBERNETES_NAMESPACE default Namespace Lambda pods are created in
FLOCI_SERVICES_LAMBDA_KUBERNETES_LABELS (unset) Extra pod labels as comma-separated key=value entries
FLOCI_SERVICES_LAMBDA_KUBERNETES_FLOCI_ADDRESS (unset) Host/IP pods use to reach Floci; auto-detected when Floci runs in-cluster
FLOCI_SERVICES_LAMBDA_KUBERNETES_INIT_IMAGE busybox:1.36 Init-container image that downloads function code (needs sh, wget, unzip)

Changing the container name prefix

Code volumes are resolved by name, and a Floci process only manages resources under its own prefix — deliberately, so multiple Floci processes with different prefixes can share one Docker daemon without touching each other's containers and volumes. Restarting with a different container-name-prefix therefore strands the code volumes (and their completion markers) created under the previous prefix: they are no longer reused and no longer part of automatic superseded-volume cleanup. They keep the prefix-independent floci=true label, so reclaim them at any time with:

docker volume prune --filter label=floci=true

Concurrent cold starts of large functions

A function whose unpacked code is at least 32 MB has that code streamed once into a read-only Docker volume, so later cold starts mount it instead of copying. Those first-time populates are capped — a burst of them overwhelms the Docker daemon — and the default cap is max(2, cpus/2), derived from the CPU count the JVM sees.

Because the JVM honours the container's cgroup CPU quota, running Floci with a small CPU allocation collapses the cap to 2, and a burst of cold starts across distinct large functions completes in waves of two rather than in parallel. Six such functions invoked at once take roughly three times the wall-clock of one. Raise the cap to decouple it from the CPU allocation:

FLOCI_SERVICES_LAMBDA_CODE_VOLUME_POPULATE_CONCURRENCY=8

Only first-time populates are gated. Warm containers, already-populated volumes, and functions under 32 MB are never serialised by this.

The temporary copy helper is removed without a stop grace period once copying finishes or fails. It runs no Lambda code; actual execution environments retain their normal shutdown and extension-drain behavior.

Cleanup after an unclean Docker shutdown

At startup, Floci removes running and exited Lambda containers left by a previous run, including temporary code-copy helpers. Cleanup is scoped to the Docker resource namespace and Floci API port, and preserves containers from the current run and named code volumes. If Docker is unavailable or removal fails, the next cold start retries cleanup.

This applies to containers created with ownership and run labels. Containers from older versions without those labels are left alone because their deployment cannot be identified safely. Use distinct FLOCI_DOCKER_RESOURCE_NAMESPACE values for deployments sharing a daemon.

If two deployments must share the same namespace and API port, set FLOCI_SERVICES_LAMBDA_RECONCILE_CONTAINERS_ON_STARTUP=false to disable both startup cleanup and cold-start retries. Cleanup is enabled by default. Each distinct Docker listing or removal failure warns once; repeated failures log at DEBUG until cleanup recovers.

Bounding warm containers

After an invocation the container stays warm so the next call skips the cold start, and is reaped only after container-idle-timeout-seconds of inactivity. Each function keeps up to warm-pool-max-per-function idle containers, but nothing limits the sum: a stack of many functions that fan out through streams and triggers can accumulate one warm container per function touched, and each runtime container holds its own memory. On a Docker Desktop with a modest memory allocation that is enough to have Floci OOM-killed. ephemeral: true avoids it by cold-starting every invocation, at a large latency cost.

warm-pool-max-total bounds the idle containers across all functions. When a release would exceed it, the least-recently-used idle container of any function is stopped first, so the function that just ran (the most likely to run again) keeps its container:

FLOCI_SERVICES_LAMBDA_WARM_POOL_MAX_TOTAL=24

This bounds idle containers only, emulator-wide. Busy containers do not count toward it; their ceiling is region-concurrency-limit, which applies independently in each region, so peak container count is warm-pool-max-total plus the in-flight invocations across every active region. A cap that is smaller than the number of functions invoked in a tight loop trades some warm hits for the memory bound. A negative value is ignored with a warning and leaves the total unbounded, like 0.

Slow cold starts

A cold start has two budgets. The Init phase runs from the moment the container has started until its runtime requests the first invocation, which covers runtime startup and the function's static initialization. The function's Timeout starts only when the invocation is handed to the runtime, so in Floci a slow init never shortens the handler's time and getRemainingTimeInMillis() reports the full Timeout. AWS differs here: an init that runs past its 10-second limit is retried with the first invocation, inside the function's Timeout, so there a slow init does eat into the handler's time.

The Init phase may last init-timeout-seconds (default 10, the limit AWS applies), counted from the container's start, so launching extensions and attaching logs use part of it. A function whose Timeout plus 2 seconds is longer than what is left of the budget waits that long instead. A runtime that has not asked for its invocation by then is stopped, the invocation fails with Function.TimedOut, and Floci logs a warning naming the setting. Java and other JVM runtimes on a busy CI host can need more than 10 seconds; raise the budget there:

FLOCI_SERVICES_LAMBDA_INIT_TIMEOUT_SECONDS=120

Image pulls and container creation happen before the Init phase and are not counted against it. The budget applies only until the runtime first requests an invocation: a warm or provisioned container whose runtime stops asking is given its Timeout plus 2 seconds. SQS event source mappings add the budget to the visibility timeout they receive messages with, so a message is not delivered to another consumer while its cold start is still within the budget.

Runtime API host override

When a Lambda container starts, it calls back into Floci's Runtime API to fetch events and post results. Floci auto-detects the address containers should use for that callback (its own container IP on the shared network, or host.docker.internal when running on the host). In most setups this is correct and needs no configuration.

On unusual network topologies, for example rootless Podman, auto-detection can pick an address the Lambda container cannot reach, and invocations fail with connect ECONNREFUSED <ip>:12000. Set FLOCI_SERVICES_LAMBDA_DOCKER_HOST_OVERRIDE to the host or IP that containers can actually reach Floci on, and Floci uses it verbatim instead of auto-detecting:

FLOCI_SERVICES_LAMBDA_DOCKER_HOST_OVERRIDE=floci

See Docker Configuration → Running on Podman (rootless) for a full rootless Podman walkthrough.

Docker socket requirement

With the default docker executor, Lambda requires the Docker socket. Mount it in your compose file:

services:
  floci:
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

If mounting the Docker socket is not acceptable (for example on a hardened Kubernetes cluster), use the Kubernetes executor instead — it needs no privileged access and no socket.

Kubernetes executor

Set FLOCI_SERVICES_LAMBDA_EXECUTOR=kubernetes to run each Lambda execution environment as a Kubernetes pod instead of a Docker container. This is designed for CI/CD clusters where privileged containers and docker.sock access are not allowed. Floci talks to the cluster through the standard Kubernetes API: when running inside the cluster it uses its ServiceAccount, and when running outside it uses your local kubeconfig. An inline static bearer token, a client-certificate/client-key credential with a PKCS#8 private key, or the aws eks get-token --cluster-name <name> [--region <region>] exec plugin (what aws eks update-kubeconfig generates) is supported. --role-arn, tokenFile, any other exec command, and auth-provider credential plugins (gcloud, etc.) are not, and fail with a named error.

How an invocation works:

  1. On a cold start Floci creates a pod from the function's runtime image (public.ecr.aws/lambda/*, same mapping as the Docker executor).
  2. An init container (busybox by default) downloads the function's deployment package — and any layers — from Floci's S3 over HTTP and unpacks them into shared emptyDir volumes at /var/task and /opt.
  3. The runtime container polls Floci's Lambda Runtime API (AWS_LAMBDA_RUNTIME_API) exactly like a Docker container would.
  4. Warm pods are reused across invocations and reaped after FLOCI_SERVICES_LAMBDA_CONTAINER_IDLE_TIMEOUT_SECONDS of inactivity. Pods left behind by a crashed Floci are swept on startup via the app.kubernetes.io/managed-by=floci label.

Lambda pods connect back to Floci on the main port (4566) and the Runtime API port range (9200–9299), so those ports must be reachable from pods in the namespace. When Floci runs in-cluster this works out of the box (pod-to-pod traffic); when Floci runs outside the cluster, set FLOCI_SERVICES_LAMBDA_KUBERNETES_FLOCI_ADDRESS to an address the cluster's pods can reach (for example your machine's LAN IP for a kind cluster).

Required RBAC

The ServiceAccount Floci runs under needs these permissions in the Lambda namespace. The manifest below is complete, so applying it as-is (together with the Deployment in the next section) yields a working setup:

apiVersion: v1
kind: ServiceAccount
metadata:
  name: floci
  namespace: floci
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: floci-lambda
  namespace: floci
rules:
  - apiGroups: [""]
    resources: ["pods"]
    verbs: ["create", "get", "list", "watch", "delete", "deletecollection"]
  - apiGroups: [""]
    resources: ["pods/log"]
    verbs: ["get", "watch"]
  # Only needed when FLOCI_TLS_ENABLED=true (the CA bundle is shared via a ConfigMap)
  - apiGroups: [""]
    resources: ["configmaps"]
    verbs: ["create", "get", "update", "patch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: floci-lambda
  namespace: floci
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: floci-lambda
subjects:
  - kind: ServiceAccount
    name: floci
    namespace: floci

Running Floci in-cluster

The Helm chart in charts/floci sets all of this up, with the RBAC above, a Lambda namespace of your choice and helm test checks: see Kubernetes (Helm). Without Helm, a minimal Deployment (namespace floci assumed, RBAC from above bound to the floci ServiceAccount):

apiVersion: apps/v1
kind: Deployment
metadata:
  name: floci
spec:
  replicas: 1
  selector:
    matchLabels: { app: floci }
  template:
    metadata:
      labels: { app: floci }
    spec:
      serviceAccountName: floci
      # Required when a Service named `floci` exists in the namespace: service
      # links inject FLOCI_PORT=tcp://<ip>:4566, which collides with Floci's
      # FLOCI_* configuration convention and fails startup.
      enableServiceLinks: false
      containers:
        - name: floci
          image: floci/floci:latest
          env:
            - name: FLOCI_SERVICES_LAMBDA_EXECUTOR
              value: kubernetes
            - name: FLOCI_SERVICES_LAMBDA_KUBERNETES_NAMESPACE
              value: floci
          ports:
            - containerPort: 4566
---
apiVersion: v1
kind: Service
metadata:
  name: floci
spec:
  selector: { app: floci }
  ports:
    - port: 4566
      targetPort: 4566

Lambda pods reach Floci by pod IP, so the Runtime API ports need no Service entries; only clients of the emulator itself use port 4566.

Limitations

  • Hot reload (both bind-mount and Reactive S3 Sync bind variants) and FLOCI_SERVICES_LAMBDA_AWS_CONFIG_PATH rely on bind mounts and are not supported; hot-reload functions fail to launch with a clear error.
  • Image package type URIs are passed to the kubelet unchanged. Images in Floci's emulated ECR registry are not pullable by cluster nodes — pre-load them onto the nodes (e.g. kind load docker-image) or use a real registry.
  • Lambda pods carry no imagePullSecrets. If your runtime or init images come from an authenticated registry, attach the pull secret to the namespace's default ServiceAccount (kubectl patch serviceaccount default -p '{"imagePullSecrets":[{"name":"<secret>"}]}') so the kubelet uses it for every pod in the namespace.
  • A cold start waits up to 300 seconds for the pod to reach Running (broken images and failing init containers are detected and reported much earlier).
  • The init container downloads code and layers over plain HTTP on the emulator port even when FLOCI_TLS_ENABLED=true. busybox wget cannot complete a TLS handshake with Floci, and the Runtime API traffic on the same pod network is plain HTTP anyway. Use a NetworkPolicy if the pod network is part of your threat model.
  • With FLOCI_TLS_ENABLED=true, AWS SDK calls made from inside the function fail TLS verification when pods reach Floci by pod IP, because the self-signed certificate carries no SAN for dynamic pod IPs. Set FLOCI_SERVICES_LAMBDA_KUBERNETES_FLOCI_ADDRESS to a hostname covered by the certificate, or provide your own certificate via floci.tls.cert-path.
  • Prefer an IP for FLOCI_SERVICES_LAMBDA_KUBERNETES_FLOCI_ADDRESS. With a bare hostname, S3 SDKs inside functions may use virtual-hosted-style addressing (bucket.<hostname>), and nothing in the cluster resolves those subdomains.
  • IPv6-only clusters are not supported. Floci advertises an IPv4 address to pods and fails fast when none is available.
  • Each Floci instance sweeps all managed-by=floci Lambda pods in its namespace at startup; run multiple Floci instances in separate namespaces.
  • Layers published by Floci versions before this feature have no stored archive; re-publish them once to make them downloadable by pods.

S3 virtual-hosted-style addressing inside Lambda containers

AWS SDKs use virtual-hosted-style S3 addressing by default, forming URLs like https://my-bucket.s3.amazonaws.com/key. Against Floci the same pattern becomes http://my-bucket.localhost.floci.io:4566/key.

When Floci runs inside Docker, Lambda containers are on the same Docker network. Docker's embedded DNS resolves the exact alias localhost.floci.io correctly, but has no wildcard support. my-bucket.localhost.floci.io falls through to public DNS and resolves to the wrong IP, causing the Lambda invocation to time out.

Floci solves this automatically by running an embedded DNS server (UDP/53) on its container IP. All Lambda containers launched by Floci are configured to use it as their DNS resolver. It binds that advertised IP so replies retain the queried source address even when the container has multiple network interfaces. The embedded DNS server:

  • Resolves *.localhost.floci.io → Floci's Docker network IP
  • Forwards all other queries to the upstream resolver(s) from /etc/resolv.conf, falling back to public resolvers so public hostnames (e.g. business-api.tiktok.com) resolve from inside Lambda containers

No extra configuration or cap_add is needed because Docker containers have CAP_NET_BIND_SERVICE in their default capability set, so Floci (running as a non-root user) can bind UDP/53 without any changes to your Compose file.

VpcConfig, SnapStart, LoggingConfig and DurableConfig

All four round-trip through CreateFunction, UpdateFunctionConfiguration, GetFunctionConfiguration, GetFunction, ListFunctions and PublishVersion.

The response shapes are not the request shapes, and Floci follows the AWS model rather than echoing the request back:

Field Request shape Response shape Extra members Floci fills in
VpcConfig VpcConfig VpcConfigResponse VpcId, shared by all declared subnets and security groups
SnapStart SnapStart SnapStartResponse OptimizationStatus — On only for a published version with ApplyOn=PublishedVersions, Off for $LATEST
LoggingConfig LoggingConfig LoggingConfig —
DurableConfig DurableConfig DurableConfig RetentionPeriodInDays defaults to 14; omitted for a function created without it

SnapStart and LoggingConfig are always present in a response, as on AWS: an unset function reads back SnapStart={ApplyOn: None, OptimizationStatus: Off} and LoggingConfig={LogFormat: Text, LogGroup: /aws/lambda/<name>}. With LogFormat=JSON, ApplicationLogLevel and SystemLogLevel are also returned, defaulting to INFO. Terraform treats these as Computed blocks, so a missing one is a permanent diff rather than a cosmetic omission.

LoggingConfig is replaced wholesale on update, not merged — an update naming only LogFormat resets LogGroup to the default.

A function's execution environments write their logs, START, END and REPORT included, to the LogGroup its LoggingConfig names, creating the group when it does not exist, and AWS_LAMBDA_LOG_GROUP_NAME names that group. Once a group is named, which several functions can share, each stream's name carries the function's name, as on AWS: 2026/10/16/my-fn[$LATEST]<id> rather than the default group's 2026/10/16/[$LATEST]<id>.

For a synchronous Invoke, LogType=Tail returns the last 4,096 bytes of that invocation's standard output and standard error, base64-encoded in X-Amz-Log-Result (LogResult in the SDK and CLI). The first invocation also includes initialization output. A warm invocation's tail excludes earlier invocations in the same environment. LogType=None, an omitted log type, Event and DryRun omit the header. CloudWatch log forwarding continues independently.

Warm invocation boundaries come from the Docker daemon's or kubelet's log timestamps, so differences between Floci's clock and the log source's clock do not affect filtering. Kubernetes snapshots also filter timestamps locally at nanosecond precision. Synchronous durable invocations return a bounded tail across their handler invocations, including logs produced after a checkpoint completes the execution and before the handler returns.

The execution environment gets AWS_LAMBDA_LOG_FORMAT from LogFormat and, under LogFormat=JSON, AWS_LAMBDA_LOG_LEVEL from ApplicationLogLevel (INFO when unset, the level the API reports). The runtime interface clients read both: a Python function writes each record as a JSON object, extra keys included, and drops records under the level.

DurableConfig requires ExecutionTimeout on create. A durable function created without a Timeout gets min(ExecutionTimeout, 900). It always logs in JSON format, and LogFormat: Text is rejected. On update the members are merged, and a function created without DurableConfig cannot gain one. CloudFormation and Terraform (durable_config) replace the function to add or remove it. See Durable Functions for the execution itself.

LogGroup is validated against AWS's documented constraint: 1-512 characters matching [.\-_/#A-Za-z0-9]+. ApplicationLogLevel and SystemLogLevel belong to LogFormat=JSON: a log level under Text, whether LogFormat names Text or is left to that default, is refused on create and on update with InvalidParameterValueException ("LogLevel is not supported when LogFormat is set to "Text". Remove LogLevel from your request or change the LogFormat to "JSON" and try again."), as Lambda refuses it (measured in eu-west-1, 2026-10-18).

VpcConfig accepts placeholder subnet and security-group IDs that are unknown in Floci's request account and region. This local compatibility behavior preserves the requested IDs but omits VpcId whenever any requested resource is unknown. Known subnets and security groups must still belong to one VPC, even when the request also contains unknown IDs. Mixed known VPCs or specifying only subnets or only security groups fail with InvalidParameterValueException before the function is mutated. A rejected update preserves the configuration and revision. Empty subnet and security group lists detach the function, and the response then omits VpcConfig. Published versions retain their network configuration when $LATEST changes.

As on AWS, where a function's network interfaces sit in the subnets its VpcConfig names, EC2's DeleteSubnet and DeleteVpc fail with DependencyViolation while a function, or a published version of one, names the subnet or is configured in the VPC.

These checks validate the declaration. Function containers still use the configured Docker network. With Docker-backed VPC networks (FLOCI_SERVICES_EC2_VPC_NETWORKS_ENABLED=true and FLOCI_SERVICES_EC2_MOCK=false) and a known VpcId, the container also joins that VPC's Docker network at an address leased from the first subnet in SubnetIds, so it reaches EC2 instances and awsvpc ECS tasks in the VPC at the private addresses they report. The address is returned once the container is removed. VpcConfig does not yet enforce security-group rules or NAT egress, and the other subnets are not used.

RuntimeVersionConfig.RuntimeVersionArn is returned for managed (non-image) runtimes. Its value is derived from the runtime name, so it is stable across restarts.

File system configs

FileSystemConfigs accepts one EFS access point and mounts it under the requested /mnt/... path for local Lambda containers. As on AWS, the function must include VPC subnet and security group configuration. The mounted path uses the same shared-volume initialization settings as ECS EFS volumes under floci.storage.efs.

This configuration is supported through the Lambda API, AWS::Lambda::Function resources, and AWS::Serverless::Function resources.

S3 Files access points are not currently emulated and are rejected instead of being mounted as an empty local volume.

Resolving public hostnames from Lambda

A Lambda whose handler reaches a public host (fetch()/HTTPS to e.g. business-api.tiktok.com) resolves it through Floci's embedded DNS. As a safety net, Floci also appends configurable public resolvers (default 8.8.8.8, 8.8.4.4) after its own IP on each spawned container's DNS list, so name resolution still works if the embedded forwarder cannot answer.

Explicit --dns flags replace those automatic resolvers. In that case, the injected AWS_ENDPOINT_URL uses the reachable Docker host address instead of a hostname that requires Floci's resolver.

Tune or disable this for offline / locked-down networks where those resolvers are blocked:

FLOCI_DNS_CONTAINER_FALLBACK_SERVERS=1.1.1.1,1.0.0.1   # use different resolvers
FLOCI_DNS_CONTAINER_FALLBACK_ENABLED=false             # inject only Floci's DNS

Docker Compose service names

If Floci runs as a Docker Compose service, set FLOCI_HOSTNAME to the service name, for example FLOCI_HOSTNAME=floci. When no explicit Lambda Docker network is configured, Floci automatically attaches Lambda containers to the current Compose network. Floci then injects AWS_ENDPOINT_URL=http://floci:4566 into Lambda containers and returns SQS QueueUrl values with the same reachable host.

This avoids function-side rewrites from localhost or localhost.floci.io to floci, and keeps normal AWS SDK clients pointed at the Docker DNS name that the Lambda container can resolve.

Path-style as a workaround

If you cannot use virtual-hosted-style (e.g. Floci is running natively on the host, not in Docker), configure the SDK client with forcePathStyle: true / s3ForcePathStyle: true. Requests will go to http://localhost:4566/my-bucket/key instead and work without DNS.

Migrating from LocalStack

If your Lambda functions have AWS_ENDPOINT_URL=http://localhost.localstack.cloud:4566 hardcoded, add the LocalStack suffix to Floci's DNS resolver so it resolves to Floci's IP without any function-side changes:

Via environment variable, use a comma-separated list for multiple suffixes:

# Single suffix
FLOCI_DNS_EXTRA_SUFFIXES=localhost.localstack.cloud

# Multiple suffixes
FLOCI_DNS_EXTRA_SUFFIXES=localhost.localstack.cloud,localhost.example.internal

Real AWS Credentials

By default, a Lambda function whose execution role exists in Floci's IAM store receives temporary credentials for that role. SDK calls made by the function identify as assumed-role/<role>/<function-name>, and IAM enforcement evaluates the role's policies. If the role is unknown to Floci, the container keeps the compatibility fallback described below.

For hybrid local/cloud testing, where some services are emulated and others hit real AWS, you can mount your host ~/.aws directory into Lambda containers:

services:
  floci:
    image: floci/floci:latest
    environment:
      FLOCI_SERVICES_LAMBDA_AWS_CONFIG_PATH: /Users/me/.aws
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

When aws-config-path is set:

  • The host path is bind-mounted read-only into each Lambda container at /opt/aws-config
  • AWS_SHARED_CREDENTIALS_FILE and AWS_CONFIG_FILE env vars are set so the SDK discovers credentials regardless of the container's HOME directory
  • No AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / AWS_SESSION_TOKEN env vars are injected

When unset (default), Floci injects execution-role credentials for a known role. For an unknown role, Floci reads credentials from its own environment and falls back to test/test/test.

Routing specific services to real AWS

To keep some services on Floci while others hit real AWS, clear the global endpoint and set service-specific overrides in your function's --environment:

AWS_ENDPOINT_URL=                                          # clear Floci's global endpoint
AWS_ENDPOINT_URL_SES=http://localhost.floci.io:4566       # SES stays on Floci
AWS_ENDPOINT_URL_CLOUDWATCHLOGS=http://localhost.floci.io:4566  # CloudWatch stays on Floci

The AWS SDK supports AWS_ENDPOINT_URL_<SERVICE> natively. Services without an override will use real AWS endpoints.

Credential passthrough without mounting

For functions whose execution role is unknown to Floci, you can pass static credentials to Floci's environment directly. When aws-config-path is unset, Floci forwards its own AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN env vars into those Lambda containers:

environment:
  AWS_ACCESS_KEY_ID: ${AWS_ACCESS_KEY_ID}
  AWS_SECRET_ACCESS_KEY: ${AWS_SECRET_ACCESS_KEY}
  AWS_SESSION_TOKEN: ${AWS_SESSION_TOKEN}

A known execution role takes precedence over AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN values in the function environment. Use aws-config-path when the function must use mounted credentials instead of its emulated execution role.

Passthrough is on whenever those three variables are set in Floci's own environment, so a Floci started from a shell that exports real AWS credentials (aws-vault exec, a sourced credentials file, a CI runner) hands them to any function whose role it does not know. An AWS_PROFILE or an aws sso login alone does not do this: those populate config and cache files, not the environment. Floci logs a WARN carrying the forwarded access-key prefix the first time it happens. Give the function a role Floci knows, or set aws-config-path, to keep host credentials out of the container.

Locally built images

A container image function whose ImageUri names an image already present on the Docker daemon runs that image directly. This includes AWS-shaped <account>.dkr.ecr.<region>.amazonaws.com/<repo>:<tag> URIs, which are otherwise rewritten to Floci's emulated ECR registry at pull time: build the image under the exact URI the function declares (docker build -t <ImageUri> .) and no push is needed. With FLOCI_DOCKER_IMAGE_REGISTRY_BASE set, tag it as <base>/<ImageUri> instead, since that is the reference Floci launches. Set FLOCI_SERVICES_ECR_PREFER_LOCAL_IMAGES=false to always resolve AWS-shaped URIs through the emulated registry.

Private registry authentication

Container image functions ("PackageType": "Image") that pull from private registries need Docker credentials. See Docker Configuration → Private Registry Authentication for the full guide.

Image user and working directory

AWS runs a container image function as its own least-privileged user, not the image's USER. Floci keeps running the container as the image's user, but before it starts the container it checks that Lambda's user could enter the working directory (ImageConfig.WorkingDirectory, or the image's WORKDIR). Lambda's user owns nothing in the image, so a directory on that path must be executable by other users. Symlinks on the path are followed, and the check stops at a file system the function mounts from EFS, which Lambda enters as the access point's user. When a directory is not executable by other users, such as a 0700 home directory owned by the image's user, the invocation fails with Runtime.InvalidEntrypoint, as on AWS. Set WORKDIR to a directory everyone can enter, such as /.

Examples

export AWS_ENDPOINT_URL=http://localhost:4566

# Package a simple Node.js function
cat > index.mjs << 'EOF'
export const handler = async (event) => {
  console.log("Event:", JSON.stringify(event));
  return { statusCode: 200, body: JSON.stringify({ hello: "world" }) };
};
EOF
zip function.zip index.mjs

# Deploy the function
aws lambda create-function \
  --function-name my-function \
  --runtime nodejs22.x \
  --role arn:aws:iam::000000000000:role/lambda-role \
  --handler index.handler \
  --zip-file fileb://function.zip \
  --endpoint-url $AWS_ENDPOINT_URL

# Invoke synchronously
aws lambda invoke \
  --function-name my-function \
  --payload '{"key":"value"}' \
  --cli-binary-format raw-in-base64-out \
  response.json \
  --endpoint-url $AWS_ENDPOINT_URL

cat response.json

# Invoke asynchronously
aws lambda invoke \
  --function-name my-function \
  --invocation-type Event \
  --payload '{"key":"value"}' \
  --cli-binary-format raw-in-base64-out \
  /dev/null \
  --endpoint-url $AWS_ENDPOINT_URL

# Update code
zip function.zip index.mjs
aws lambda update-function-code \
  --function-name my-function \
  --zip-file fileb://function.zip \
  --endpoint-url $AWS_ENDPOINT_URL

Event Source Mappings

Connect Lambda to SQS, Kinesis, or DynamoDB Streams. Self-managed Apache Kafka event source mappings are accepted, validated, persisted, and returned on the wire, but Floci does not run an active Kafka consumer poller:

For DynamoDB Streams mappings, Floci retries failed batches with exponential backoff, honors MaximumRetryAttempts and MaximumRecordAgeInSeconds, and sends discarded batches to configured SQS, SNS, or S3 DestinationConfig.OnFailure destinations. With BisectBatchOnFunctionError, a batch that fails with a function error is split in half and retried, narrowing it down to the failing record, which then follows the normal retry and record age rules. Splits do not count as retry attempts, and only function errors split: throttles do not, and a partial batch response retries from the reported record. If the OnFailure destination refuses a discarded batch, Floci logs the failure, drops the batch and advances past it.

For Kinesis mappings, a function error leaves the shard checkpoint in place and the same batch is retried with exponential backoff. With FunctionResponseTypes: ["ReportBatchItemFailures"], a partial batch response moves the checkpoint up to the lowest reported record and retries from there, and a malformed response retries the whole batch. Each of these retries counts toward MaximumRetryAttempts; when a partial batch response moves the checkpoint forward, the attempts count again from the new checkpoint, as they do for DynamoDB Streams. When the attempts run out, or a failed batch is older than MaximumRecordAgeInSeconds, Floci discards the batch: it sends one invocation record with a KinesisBatchInfo block to the SQS, SNS, or S3 DestinationConfig.OnFailure destination, if one is set, moves the checkpoint past the batch and goes on with the next records of the shard. If the destination refuses the record, Floci logs the failure and discards the batch all the same. With the defaults (-1 or unset) a failing batch is retried until it succeeds. A throttle leaves the checkpoint in place, without a backoff and without using an attempt, until the batch is older than MaximumRecordAgeInSeconds: then it is discarded the same way, with an approximateInvokeCount of the invocations that ran. The record age is checked only when an invoke fails or is throttled, so records are not dropped before their first invoke. With BisectBatchOnFunctionError, a batch that fails with a function error is split in half and retried, as for DynamoDB Streams, narrowing it down to the failing record, which then follows the normal retry and record age rules. Splits do not count as retry attempts, and a batch already older than MaximumRecordAgeInSeconds is discarded rather than split. FunctionResponseTypes can be set or cleared on an existing mapping with UpdateEventSourceMapping.

For both stream sources, the first retry waits twice FLOCI_SERVICES_LAMBDA_POLL_INTERVAL_MS (2 seconds by default), and each later retry waits twice as long as the one before, up to 60 seconds.

For SQS mappings, a function error returns every delivered message to the queue with the queue's VisibilityTimeout, so it is received again after that timeout and the queue's RedrivePolicy applies as usual. With FunctionResponseTypes: ["ReportBatchItemFailures"], only the messages the function reports are returned and the rest are deleted; a malformed response returns the whole batch.

A DynamoDB Streams mapping created with StartingPosition: LATEST delivers only records written after it is created, so a stream that is empty at creation delivers everything written later. After a restart it still resumes from the trim horizon, because native stream records are volatile. Deleting or disabling a mapping stops any poll that has not yet invoked the function. An invocation already running completes, but its checkpoint is not saved: a deleted mapping is never recreated and its result is dropped, and a disabled mapping re-reads that batch when it is enabled again.

# SQS trigger
QUEUE_ARN=$(aws sqs get-queue-attributes \
  --queue-url $AWS_ENDPOINT_URL/000000000000/orders \
  --attribute-names QueueArn \
  --query Attributes.QueueArn --output text \
  --endpoint-url $AWS_ENDPOINT_URL)

aws lambda create-event-source-mapping \
  --function-name my-function \
  --event-source-arn $QUEUE_ARN \
  --batch-size 10 \
  --endpoint-url $AWS_ENDPOINT_URL

MaximumBatchingWindowInSeconds (SQS)

CreateEventSourceMapping and UpdateEventSourceMapping accept a MaximumBatchingWindowInSeconds integer between 0 and 300. GetEventSourceMapping and ListEventSourceMappings echo it back when set; responses omit the field when it was never configured. Values outside 0 to 300 are rejected with InvalidParameterValueException.

When the window is greater than 0, the SQS poller holds an underfilled batch open, accumulating messages across polls, and invokes the function once the batch reaches BatchSize or the window elapses since the first buffered message, whichever comes first. A window of 0 (or an unset window) invokes as soon as any message is available, which is the previous behaviour.

aws lambda create-event-source-mapping \
  --function-name my-function \
  --event-source-arn $QUEUE_ARN \
  --batch-size 10 \
  --maximum-batching-window-in-seconds 5 \
  --endpoint-url $AWS_ENDPOINT_URL

ScalingConfig (SQS only)

CreateEventSourceMapping and UpdateEventSourceMapping accept a ScalingConfig.MaximumConcurrency integer between 2 and 1000 on SQS event sources, matching the AWS wire format. GetEventSourceMapping and ListEventSourceMappings echo the value back when set; responses omit the ScalingConfig field entirely when no cap is configured.

aws lambda create-event-source-mapping \
  --function-name my-function \
  --event-source-arn $QUEUE_ARN \
  --scaling-config MaximumConcurrency=5 \
  --endpoint-url $AWS_ENDPOINT_URL

Validation mirrors AWS: values outside 2–1000 are rejected with InvalidParameterValueException, and ScalingConfig on a non-SQS event source (Kinesis / DynamoDB Streams) is also rejected. Those services use ParallelizationFactor instead, which is a separate field.

Enforcement status

The configured MaximumConcurrency is persisted and returned on the wire, but the SQS poller does not yet cap concurrent invocations at this value (the poller today serializes invocations per ESM to one at a time regardless). Real parallel dispatch capped by MaximumConcurrency is tracked as a follow-up.

ParallelizationFactor (Kinesis and DynamoDB Streams only)

CreateEventSourceMapping and UpdateEventSourceMapping accept a ParallelizationFactor integer between 1 and 10 on Kinesis and DynamoDB Streams event sources. GetEventSourceMapping, ListEventSourceMappings and the create, update and delete responses return it on every stream mapping, 1 when none was set, as AWS does. SQS mappings omit it.

aws lambda create-event-source-mapping \
  --function-name my-function \
  --event-source-arn $STREAM_ARN \
  --starting-position LATEST \
  --parallelization-factor 4 \
  --endpoint-url $AWS_ENDPOINT_URL

Values outside 1 to 10 are rejected with InvalidParameterValueException, and so is ParallelizationFactor on any other event source.

Enforcement status

The configured ParallelizationFactor is persisted and returned on the wire, but the Kinesis and DynamoDB Streams pollers still process one batch per shard at a time. Concurrent batches per shard are tracked as a follow-up.

FilterCriteria

CreateEventSourceMapping and UpdateEventSourceMapping accept a FilterCriteria with up to 5 Filters, each carrying an event-pattern Pattern, using the same EventBridge pattern syntax as EventBridge Pipes. GetEventSourceMapping and ListEventSourceMappings echo it back when set and omit the field entirely when unset. Filters are enforced in the Kinesis, DynamoDB Streams, and SQS pollers: only matching records are delivered to the function.

aws lambda create-event-source-mapping \
  --function-name my-function \
  --event-source-arn $QUEUE_ARN \
  --filter-criteria '{"Filters":[{"Pattern":"{\"body\":{\"type\":[\"order\"]}}"}]}' \
  --endpoint-url $AWS_ENDPOINT_URL

A pattern addresses each record the way its source presents it, matching AWS:

Source Filter key Notes
SQS body (+ messageAttributes, etc.) A JSON body is matched structurally; a non-JSON body cannot satisfy an object pattern and is dropped. Other top-level record fields (e.g. messageId, messageAttributes) are also addressable.
DynamoDB Streams dynamodb (+ eventName, etc.) Matches the AttributeValue-wrapped image directly. Numeric operators do not apply (AttributeValue numbers are JSON strings), matching AWS.
Kinesis data (+ partitionKey) data is matched against the base64-decoded payload (the delivered event still carries data base64-encoded); partitionKey is the supported metadata key.

Non-matching records are consumed, not retried: Kinesis and DynamoDB Streams advance the shard iterator past them (a fully filtered batch still advances the checkpoint, so a shard never stalls), and SQS deletes filtered-out messages from the queue.

Validation mirrors AWS and runs before the mapping is stored: each Pattern must be a JSON object whose field values are non-empty match arrays or nested objects, at most 5 Filters, and each Pattern at most 4096 characters: violations are rejected with InvalidParameterValueException. A FilterCriteria of {} or with an empty Filters array clears any existing filters.

Supported operators

Filtering reuses Floci's shared EventBridge matcher (the same one EventBridge Pipes and EventBridge V2 use). It supports exact match on a string, number, boolean or null, plus prefix, suffix, equals-ignore-case, exists, anything-but (a string, a non-empty array of strings and numbers, or a nested prefix), numeric comparison/value pairs using =, >, >=, <, <=, and $or. Patterns using only these behave as on AWS. As on AWS, [null] matches a field whose value is null, not a missing one (use [{"exists": false}] for that), anything-but does not match a missing field, and a record field that is an array matches when any element does.

A pattern is validated at CreateEventSourceMapping and UpdateEventSourceMapping and rejected with InvalidParameterValueException when the matcher could not satisfy it: an unknown operator, an operator AWS documents that Floci does not implement (cidr, wildcard), more than one operator in a single match element, a wrong operand type, or a malformed numeric sequence such as an odd-length array or a non-numeric value. This is stricter than AWS, which accepts several of these. The trade is deliberate: the pollers checkpoint past (Kinesis, DynamoDB) or delete (SQS) any record a pattern fails to match, so a pattern that cannot match destroys records rather than being inert, and create time is the last point at which the caller can still act on it.

SAM event sources

CloudFormation AWS::Lambda::EventSourceMapping resources forward FilterCriteria, MaximumBatchingWindowInSeconds, ScalingConfig and DestinationConfig, so a stack-created mapping behaves as one created through the Lambda API. SAM SQS, Kinesis and DynamoDB function events forward only the queue or stream, BatchSize and Enabled, so any other event property, FilterCriteria included, is dropped.

Supported Runtimes

Any runtime that has an official AWS Lambda container image works with Floci (e.g. nodejs22.x, python3.13, java21, go1.x, provided.al2023).

With the Docker and Kubernetes executors, ZIP-based provided.* runtimes execute the package's /var/task/bootstrap, falling back to /opt/bootstrap only when the package has no bootstrap. The supplied executable stays in place, so scripts that locate companion files relative to their own path continue to work. The Kubernetes init container restores executable permission on package and layer bootstrap files after extraction and installs the shared delegate in /var/runtime. Managed runtimes keep their image-provided /var/runtime unchanged.

By default, Floci builds each runtime image reference from floci.services.lambda.ecr-base-uri and the runtime tag. To pin one runtime to a full image reference, set floci.services.lambda.runtime-images in the Floci configuration:

floci:
  services:
    lambda:
      runtime-images:
        "python3.12": "public.ecr.aws/lambda/python:3.12@sha256:<digest>"

Replace <digest> with the image's full SHA-256 digest. The override applies to zip-based functions using that runtime; other runtimes retain their default images. Custom image URI passthrough and image-package functions are unaffected.

For Docker functions that share a runtime but use different CPU architectures, add platform-specific keys such as "java17.linux.amd64" and "java17.linux.arm64", each pointing to its platform manifest digest. The Docker launcher's effective platform selects that entry before the runtime-wide fallback. Enable floci.services.lambda.honour-architectures to use the function's architecture; an explicit Docker --platform takes precedence. The code-copy helper uses the same platform. With no selected Docker platform, or for the Kubernetes launcher, the runtime-wide entry and default resolution remain in effect.

Environment variables use the quoted map-key form, for example FLOCI_SERVICES_LAMBDA_RUNTIME_IMAGES__JAVA17_LINUX_ARM64__.