Run it

Run the reader on AWS Lambda

Run the reader with a private mirror per execution environment.

In short

  • Experimental. The recipe was tried by hand through a Lambda Function URL with synthetic identity and embedding services; it is not tested in CI.
  • Use a reader container with the AWS Lambda Web Adapter, S3 read access and a private mirror in /tmp.
  • Keep the writer scheduled separately and publish the namespace first.

Prepare the namespace

Use Linux x86-64 images from the same release. The example uses the 0.1.0 release image names. Resolve and pin their digests before deploying. Replace ACCOUNT_ID, KEY_ID, bucket, prefix, namespace and service URLs throughout. Use one region, here eu-central-1, and a private SSE-S3 bucket.

Publish content and an identity directory binding your OIDC subjects with the external writer. Match its embedding profile and retrieval settings exactly. Configuration schema 4.0 defaults to dense_weight = 0.5 and lexical_candidates = 200. An older publication may use different settings. See upgrades and HTTP users.

Save this as reader.toml in the container build context. FUNCTION_URL is replaced at startup. Choose provider spend limits for your own workload. Set the AWS CLI region to eu-central-1 for the commands below.

[namespace]
name = "lambda-reader"
[storage]
uri = "s3://example-bucket/fyrr"
region = "eu-central-1"
[embedding]
endpoint = "https://embeddings.example.com/v1"
model = "BAAI/bge-m3"
dimensions = 1024
api_key = { env = "FYRR_EMBEDDING_API_KEY" }
reader_live = true
[embedding.spend]
limit_microusd = 1000000
max_call_microusd = 1000
[identity]
hashing_key = { env = "FYRR_IDENTITY_KEY" }
[identity.oidc]
issuer = "https://issuer.example.com"
audience = "fyrr"
jwks_url = "https://issuer.example.com/jwks"
[reader]
mirror_path = "/tmp/fyrr-mirror"
mirror_max_bytes = 402653184
memory_max_bytes = "768MiB"
memory_headroom_bytes = "64MiB"
concurrency = 1
version_check = "per-request"
per_request_wait = "2s"
max_response_bytes = 1048576
[reader.http]
listen = "127.0.0.1:8081"
public_url = "FUNCTION_URL"

Container and secret bootstrap

Save this as Dockerfile. The matching full image supplies Python's standard library for secret retrieval. The final image runs the reader executable.

FROM ghcr.io/fyrr-ai/fyrr:0.1.0 AS runtime
USER root
RUN mkdir -p /runtime/bin /runtime/lib && \
    cp /usr/local/bin/python3.13 /runtime/bin/python3 && \
    cp /usr/local/lib/libpython3.13.so.1.0 /runtime/lib/ && \
    cp -a /usr/local/lib/python3.13 /runtime/lib/ && \
    rm -rf /runtime/lib/python3.13/site-packages
FROM public.ecr.aws/awsguru/aws-lambda-adapter:0.9.1@sha256:46d6625e68cbbdd2efab4a20245977664513f13ffef47915b000d431adcea0b4 AS adapter
FROM ghcr.io/fyrr-ai/fyrr-reader:0.1.0
COPY --from=runtime /runtime /usr/local
COPY --from=runtime /usr/lib/x86_64-linux-gnu/libssl.so.3 /usr/lib/x86_64-linux-gnu/libcrypto.so.3 /usr/lib/x86_64-linux-gnu/libz.so.1 /usr/lib/x86_64-linux-gnu/
COPY --from=adapter /lambda-adapter /opt/extensions/lambda-adapter
COPY reader.toml /app/reader.toml
COPY --chmod=755 bootstrap.py /app/bootstrap.py
ENV AWS_LWA_PORT=8081 AWS_LWA_READINESS_CHECK_PATH=/readyz \
    AWS_LWA_ASYNC_INIT=true AWS_LWA_INVOKE_MODE=buffered \
    AWS_LWA_AUTHORIZATION_SOURCE=x-fyrr-authorization \
    PYTHONDONTWRITEBYTECODE=1 LD_LIBRARY_PATH=/usr/local/lib
USER 65532:65532
WORKDIR /tmp
ENTRYPOINT ["/app/bootstrap.py"]
CMD []

Save this as bootstrap.py. It retrieves one SecureString using the execution role's temporary credentials, sets the child environment and starts the reader.

#!/usr/local/bin/python3
import datetime
import hashlib
import hmac
import json
import os
from pathlib import Path
import urllib.request

region = os.environ["AWS_REGION"]
host = f"ssm.{region}.amazonaws.com"
body = json.dumps({"Name": os.environ["FYRR_SECRET_PARAMETER"],
                   "WithDecryption": True}).encode()
now = datetime.datetime.now(datetime.timezone.utc)
date = now.strftime("%Y%m%d")
stamp = now.strftime("%Y%m%dT%H%M%SZ")
headers = {
    "content-type": "application/x-amz-json-1.1",
    "host": host,
    "x-amz-date": stamp,
    "x-amz-security-token": os.environ["AWS_SESSION_TOKEN"],
    "x-amz-target": "AmazonSSM.GetParameter",
}
names = ";".join(sorted(headers))
canonical_headers = "".join(f"{key}:{headers[key]}\n" for key in sorted(headers))
canonical = f"POST\n/\n\n{canonical_headers}\n{names}\n{hashlib.sha256(body).hexdigest()}"
scope = f"{date}/{region}/ssm/aws4_request"
to_sign = f"AWS4-HMAC-SHA256\n{stamp}\n{scope}\n{hashlib.sha256(canonical.encode()).hexdigest()}"
key = ("AWS4" + os.environ["AWS_SECRET_ACCESS_KEY"]).encode()
for part in (date, region, "ssm", "aws4_request"):
    key = hmac.new(key, part.encode(), hashlib.sha256).digest()
signature = hmac.new(key, to_sign.encode(), hashlib.sha256).hexdigest()
headers["authorization"] = (
    f"AWS4-HMAC-SHA256 Credential={os.environ['AWS_ACCESS_KEY_ID']}/{scope}, "
    f"SignedHeaders={names}, Signature={signature}"
)
request = urllib.request.Request(f"https://{host}", body, headers)
with urllib.request.urlopen(request, timeout=10) as response:
    secret = json.loads(json.load(response)["Parameter"]["Value"])
for name in ("FYRR_IDENTITY_KEY", "FYRR_EMBEDDING_API_KEY"):
    os.environ[name] = secret[name]
os.environ["HOME"] = "/tmp"
os.environ["XDG_CACHE_HOME"] = "/tmp/cache"
config = Path("/app/reader.toml").read_text().replace(
    '"FUNCTION_URL"', json.dumps(os.environ["FYRR_PUBLIC_URL"].rstrip("/") + "/mcp")
)
with open("/tmp/fyrr.toml", "w", opener=lambda path, flags: os.open(path, flags, 0o600)) as output:
    output.write(config)
os.execv("/usr/local/bin/fyrr", ["fyrr", "--config", "/tmp/fyrr.toml", "reader", "serve"])

Create a SecureString named /fyrr/lambda-reader through a protected secret workflow. Its decrypted JSON contains FYRR_IDENTITY_KEY (the writer's namespace HMAC key) and FYRR_EMBEDDING_API_KEY. Keep secret files outside the build context. Bootstrap fetches the secret on each cold start. Recycle execution environments after rotating it.

IAM and image access

Create the execution role with this trust policy.

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": {"Service": "lambda.amazonaws.com"},
    "Action": "sts:AssumeRole"
  }]
}

Pre-create /aws/lambda/fyrr-reader with your log retention policy. Attach this execution policy, substituting the actual SSM KMS key ARN for KEY_ID. For a customer-managed key, its key policy must also permit decryption.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow", "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::example-bucket/fyrr/namespaces/lambda-reader/*"
    },
    {
      "Effect": "Allow", "Action": "s3:ListBucket",
      "Resource": "arn:aws:s3:::example-bucket",
      "Condition": {"StringLike": {"s3:prefix": ["fyrr/namespaces/lambda-reader", "fyrr/namespaces/lambda-reader/*"]}}
    },
    {
      "Effect": "Allow", "Action": "ssm:GetParameter",
      "Resource": "arn:aws:ssm:eu-central-1:ACCOUNT_ID:parameter/fyrr/lambda-reader"
    },
    {
      "Effect": "Allow", "Action": "kms:Decrypt",
      "Resource": "arn:aws:kms:eu-central-1:ACCOUNT_ID:key/KEY_ID",
      "Condition": {"StringEquals": {
        "kms:ViaService": "ssm.eu-central-1.amazonaws.com",
        "kms:EncryptionContext:PARAMETER_ARN": "arn:aws:ssm:eu-central-1:ACCOUNT_ID:parameter/fyrr/lambda-reader"
      }}
    },
    {
      "Effect": "Allow", "Action": ["logs:CreateLogStream", "logs:PutLogEvents"],
      "Resource": "arn:aws:logs:eu-central-1:ACCOUNT_ID:log-group:/aws/lambda/fyrr-reader:log-stream:*"
    }
  ]
}

The reader uses object GETs, range GETs, HEADs and prefix listings. s3:GetObject covers HEAD and conditional reads as well as GET, while s3:ListBucket covers listings. This policy assumes SSE-S3 content. SSE-KMS content also requires decrypt access to its own key. AWS S3 permission mapping.

Push a single-platform linux/amd64 image to ECR in the function's region. Use this repository policy for Lambda image retrieval.

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": {"Service": "lambda.amazonaws.com"},
    "Action": ["ecr:BatchGetImage", "ecr:GetDownloadUrlForLayer"],
    "Condition": {"ArnLike": {
      "aws:sourceArn": "arn:aws:lambda:eu-central-1:ACCOUNT_ID:function:fyrr-reader"
    }}
  }]
}

The deployment identity needs separate permissions to push images, create resources and pass the execution role.

Create the function and URL

Create a container-image function named fyrr-reader using the ECR image. Use these settings and replace the two deployment environment values.

SettingValue
Architecturex86_64
Memory1024 MB (1 GiB)
Timeout60 seconds
Ephemeral storage512 MiB
Reserved concurrency2
FYRR_SECRET_PARAMETER/fyrr/lambda-reader
FYRR_PUBLIC_URLInitially https://placeholder.example.com/

Lambda supplies AWS_REGION, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and AWS_SESSION_TOKEN. Create the URL and set the concurrency limit.

aws lambda create-function-url-config --function-name fyrr-reader --auth-type AWS_IAM --invoke-mode BUFFERED
aws lambda put-function-concurrency --function-name fyrr-reader --reserved-concurrent-executions 2

Before invoking, replace FYRR_PUBLIC_URL with the returned Function URL, preserving all other environment entries, and wait for the configuration update to finish. Bootstrap forms the exact /mcp URL so the forwarded Host matches the reader's configuration.

Callers need lambda:InvokeFunctionUrl and lambda:InvokeFunction scoped to this function. They sign requests with SigV4 for service lambda and send their OIDC token in x-fyrr-authorization: Bearer <token>. The adapter maps that header to application authentication. MCP clients need this signing path. See AWS Function URL authentication.

Limitations

Edit this page on GitHub ↗