Environment Variables
Every Simfra setting is controlled by an environment variable. Unset variables use their defaults. Boolean variables accept true/false, 1/0, or yes/no.
Core
| Variable | Default | Description |
|---|---|---|
SIMFRA_PORT |
4599 |
HTTP listen port. All AWS services are multiplexed on this single port. |
SIMFRA_HOST |
0.0.0.0 |
Bind address for the HTTP server. |
SIMFRA_DEFAULT_REGION |
us-east-1 |
Default AWS region when not specified in the request. |
SIMFRA_DEFAULT_ACCOUNT_ID |
000000000000 |
Default AWS account ID for the root account. |
SIMFRA_ROOT_ACCESS_KEY_ID |
AKIAIOSFODNN7EXAMPLE |
Access key ID for the root account. Used for SigV4 authentication. |
SIMFRA_ROOT_SECRET_ACCESS_KEY |
wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY |
Secret access key for the root account. |
SIMFRA_LOG_LEVEL |
info |
Log verbosity. One of debug, info, warn, error. |
SIMFRA_ADMIN_TOKEN |
(empty) | Bearer token for the /_simfra/ admin API. When empty, the admin API is unauthenticated. |
SIMFRA_REQUEST_TIMEOUT |
60 |
Maximum request duration in seconds before the gateway cancels the handler. |
SIMFRA_FIDELITY |
default |
Simulation fidelity mode. exact disables jitter, default is balanced, realistic enables distributed behaviors. |
Persistence
| Variable | Default | Description |
|---|---|---|
SIMFRA_DATA_DIR |
(empty) | Directory for persistent storage. When set, resource metadata is written to SQLite and S3 objects are stored on the filesystem. When empty, all state is ephemeral (in-memory only). |
SIMFRA_PERSISTENCE_KEY |
(empty) | AES-256 encryption key for sensitive fields in the SQLite database, as a 64-character hex string (32 bytes). When empty, a key is auto-generated and stored in $SIMFRA_DATA_DIR/.master_key. |
Bootstrap
| Variable | Default | Description |
|---|---|---|
SIMFRA_BOOTSTRAP |
(empty) | Account initialization mode. standard creates default VPCs, KMS keys, and IAM SLRs in 16 regions. A filesystem path (e.g., /path/to/terraform) runs terraform init + apply from that directory against Simfra. When empty, no bootstrapping occurs. |
Docker
| Variable | Default | Description |
|---|---|---|
SIMFRA_DOCKER |
false |
Enable Docker-backed services (Lambda, EC2, RDS, ELBv2, EKS, etc.). Requires access to the Docker socket. |
SIMFRA_DOCKER_IMAGE_REGISTRY |
(empty) | Override the default registry prefix for all Docker images Simfra pulls (sidecars, databases, runtimes, infrastructure). Set this instead of overriding each service image individually. |
SIMFRA_DOCKER_IMAGE_TAG |
(empty) | Override the default tag for Simfra sidecar container images. |
SIMFRA_DOCKER_CLEANUP_ON_START |
true |
Remove stale Simfra Docker containers and networks on startup. |
SIMFRA_DOCKER_CLEANUP_ON_SHUTDOWN |
true |
Remove Simfra Docker containers and networks on graceful shutdown. |
SIMFRA_VPC_ISOLATION |
Same as SIMFRA_DOCKER |
Enable VPC network isolation. Private containers (internal LBs, private RDS) don't publish ports to the host. Defaults to true when Docker is enabled. |
SIMFRA_CONTAINERIZED |
(auto-detected) | Indicate that Simfra itself is running inside a Docker container. Auto-detected via /.dockerenv. Affects Docker-reachable IP detection. |
Networking
| Variable | Default | Description |
|---|---|---|
SIMFRA_HOSTNAME |
simfra.local |
Hostname that containers use to reach Simfra. Resolved by the DNS container. |
SIMFRA_DOMAIN_SUFFIX |
simfra.dev |
Domain suffix for service DNS names (e.g., ALB DNS names become *.elb.simfra.dev). |
Service Images
Override Docker images for specific services. Useful for air-gapped environments, custom builds, or pinning versions.
EC2
| Variable | Default | Description |
|---|---|---|
SIMFRA_EC2_DEFAULT_IMAGE |
amazonlinux:2023 |
Default Docker image for EC2 instances when no AMI match is found. |
SIMFRA_EC2_IMAGE_AMAZONLINUX2 |
amazonlinux:2 |
Image for Amazon Linux 2 AMIs. |
SIMFRA_EC2_IMAGE_AMAZONLINUX2023 |
amazonlinux:2023 |
Image for Amazon Linux 2023 AMIs. |
SIMFRA_EC2_IMAGE_UBUNTU |
ubuntu:latest |
Image for Ubuntu AMIs. |
SIMFRA_EC2_IMAGE_DEBIAN |
debian:latest |
Image for Debian AMIs. |
SIMFRA_IMDS_LINK_LOCAL |
false |
Enable IMDS on the link-local address 169.254.169.254 inside EC2 containers. |
Lambda
| Variable | Default | Description |
|---|---|---|
SIMFRA_LAMBDA_IMAGE_REGISTRY |
public.ecr.aws/lambda |
Registry for Lambda runtime base images (e.g., public.ecr.aws/lambda/python:3.12). |
SIMFRA_LAMBDA_KEEP_ALIVE |
300 |
Seconds to keep idle Lambda containers alive before recycling. |
RDS
| Variable | Default | Description |
|---|---|---|
SIMFRA_RDS_IMAGE_MYSQL |
mysql:8.0 |
Docker image for MySQL RDS instances. |
SIMFRA_RDS_IMAGE_POSTGRES |
postgres:16 |
Docker image for PostgreSQL RDS instances. |
SIMFRA_RDS_IMAGE_MARIADB |
mariadb:10.11 |
Docker image for MariaDB RDS instances. |
ElastiCache
| Variable | Default | Description |
|---|---|---|
SIMFRA_ELASTICACHE_IMAGE_REDIS |
redis:7 |
Docker image for Redis ElastiCache clusters. |
SIMFRA_ELASTICACHE_IMAGE_VALKEY |
valkey/valkey:8 |
Docker image for Valkey ElastiCache clusters. |
SIMFRA_ELASTICACHE_IMAGE_MEMCACHED |
memcached:1.6 |
Docker image for Memcached ElastiCache clusters. |
Amazon MQ
| Variable | Default | Description |
|---|---|---|
SIMFRA_MQ_IMAGE_ACTIVEMQ |
apache/activemq-classic:5.18.6 |
Docker image for ActiveMQ brokers. |
SIMFRA_MQ_IMAGE_RABBITMQ |
rabbitmq:3.13-management |
Docker image for RabbitMQ brokers. |
Amazon MSK
| Variable | Default | Description |
|---|---|---|
SIMFRA_KAFKA_IMAGE |
apache/kafka:3.9.0 |
Docker image for Kafka (KRaft mode) clusters. |
OpenSearch
| Variable | Default | Description |
|---|---|---|
SIMFRA_OPENSEARCH_IMAGE |
opensearchproject/opensearch:2.19.1 |
Docker image for OpenSearch domains. |
Redshift
| Variable | Default | Description |
|---|---|---|
SIMFRA_REDSHIFT_IMAGE |
postgres:16 |
Docker image for Redshift clusters (PostgreSQL-compatible). |
DSQL
| Variable | Default | Description |
|---|---|---|
SIMFRA_DSQL_IMAGE |
postgres:16 |
Docker image for DSQL clusters (PostgreSQL-compatible). |
Bedrock
| Variable | Default | Description |
|---|---|---|
SIMFRA_BEDROCK_IMAGE_BACKEND |
sdcpp |
LLM inference backend. ollama or sdcpp. |
SIMFRA_BEDROCK_OLLAMA_IMAGE |
(uses sidecar registry) | Docker image for the Ollama inference server. Defaults to simfra-ollama with the default model pre-baked. |
SIMFRA_BEDROCK_SDCPP_IMAGE |
(empty) | Docker image for the stable-diffusion.cpp inference server. |
SIMFRA_BEDROCK_OLLAMA_GPU |
(empty) | GPU device to pass to the Ollama container (e.g., nvidia, all). |
SIMFRA_BEDROCK_DEFAULT_MODEL |
llama3.2 |
Default Ollama model to use when no model mapping matches. |
SIMFRA_BEDROCK_MODEL_MAP |
(empty) | Custom mapping of Bedrock model IDs to Ollama model names (comma-separated bedrock=ollama pairs). |
SIMFRA_BEDROCK_CACHE_MODELS |
true |
Pre-pull models into the Ollama container on startup. |
Other
| Variable | Default | Description |
|---|---|---|
SIMFRA_SSM_FLUENTBIT_REGISTRY |
public.ecr.aws/aws-observability/aws-for-fluent-bit |
Registry for the Fluent Bit image used by SSM agent log forwarding. |
SIMFRA_CLOUDSHELL_IDLE_TIMEOUT |
1200 |
Seconds before an idle CloudShell session is terminated (default 20 minutes). |
SIMFRA_IRSA_WEBHOOK_PORT |
0 |
HTTPS port for the EKS IRSA webhook. 0 means SIMFRA_PORT + 1. |
Port Ranges
Port ranges are specified as START-END (e.g., 10200-10299). Set to 0 for random port allocation.
| Variable | Default | Description |
|---|---|---|
SIMFRA_DNS_PORT_RANGE |
10000-10099 |
Host ports for DNS containers. |
SIMFRA_SMTP_PORT_RANGE |
10100-10199 |
Host ports for SES SMTP containers. |
SIMFRA_ELBV2_PORT_RANGE |
10200-10299 |
Host ports for ELBv2 load balancer containers. |
SIMFRA_APIGW_PORT_RANGE |
10300-10399 |
Host ports for API Gateway containers. |
SIMFRA_RDS_PORT_RANGE |
10400-10499 |
Host ports for RDS database containers. |
SIMFRA_RDS_PROXY_PORT_RANGE |
10500-10599 |
Host ports for RDS Proxy containers. |
SIMFRA_EFS_PORT_RANGE |
10600-10699 |
Host ports for EFS NFS containers. |
SIMFRA_COGNITO_AUTH_PORT_RANGE |
10700-10799 |
Host ports for Cognito hosted UI containers. |
SIMFRA_CLOUDFRONT_PORT_RANGE |
10800-10899 |
Host ports for CloudFront CDN containers. |
SIMFRA_ELASTICACHE_PORT_RANGE |
10900-10999 |
Host ports for ElastiCache containers. |
SIMFRA_REDSHIFT_PORT_RANGE |
11000-11099 |
Host ports for Redshift containers. |
SIMFRA_GLUE_PORT_RANGE |
11100-11199 |
Host ports for Glue job containers. |
SIMFRA_MQ_PORT_RANGE |
11200-11299 |
Host ports for Amazon MQ broker containers. |
SIMFRA_KAFKA_PORT_RANGE |
11300-11399 |
Host ports for MSK Kafka containers. |
SIMFRA_OPENSEARCH_PORT_RANGE |
11400-11499 |
Host ports for OpenSearch containers. |
SIMFRA_DS_PORT_RANGE |
11500-11599 |
Host ports for Directory Service containers. |
SIMFRA_DSQL_PORT_RANGE |
11600-11699 |
Host ports for DSQL containers. |
SIMFRA_CODECOMMIT_PORT_RANGE |
11700-11799 |
Host ports for CodeCommit git containers. |
SIMFRA_PORT_FORWARD_PORT_RANGE |
11800-11899 |
Host ports for SSM port forwarding sessions. |
SIMFRA_PORT_FORWARD_IDLE_TIMEOUT |
7200 |
Seconds before an idle port-forward session is closed (default 2 hours). |
SQS Behavior
| Variable | Default | Description |
|---|---|---|
SIMFRA_SQS_DELAY_RECENTLY_DELETED |
true |
Enforce the 60-second recently-deleted queue delay, matching AWS behavior. Set to false for faster test iteration. |
SIMFRA_SQS_DELAY_PURGE_RETRY |
true |
Enforce the 60-second purge retry delay. Set to false for faster test iteration. |