Floci accepts any non-empty credentials — no real AWS account is needed. The sections below cover every way to direct the AWS CLI and AWS SDKs at your local Floci instance.
Environment variables
The simplest approach for local development is to export a set of shell variables. Because AWS_ENDPOINT_URL is an official AWS CLI environment variable, no --endpoint-url flag is needed on individual commands.
export AWS_ENDPOINT_URL=http://localhost:4566
export AWS_DEFAULT_REGION=us-east-1
export AWS_ACCESS_KEY_ID=test
export AWS_SECRET_ACCESS_KEY=test
Setting AWS_ENDPOINT_URL globally means every aws command you run in that shell automatically targets Floci — no per-command flag required.
Persistent shell profile
To apply these variables automatically in every terminal session, add them to your shell profile:
# ~/.bashrc or ~/.zshrc
export AWS_ENDPOINT_URL=http://localhost:4566
export AWS_DEFAULT_REGION=us-east-1
export AWS_ACCESS_KEY_ID=test
export AWS_SECRET_ACCESS_KEY=test
source ~/.bashrc # or source ~/.zshrc
AWS config file
Add a dedicated floci profile to ~/.aws/config and ~/.aws/credentials:
# ~/.aws/config
[profile floci]
region = us-east-1
output = json
endpoint_url = http://localhost:4566
# ~/.aws/credentials
[floci]
aws_access_key_id = test
aws_secret_access_key = test
aws s3 ls --profile floci
Per-command flag
Pass --endpoint-url directly when you only need to override the endpoint for a single command:
aws s3 mb s3://my-bucket --endpoint-url http://localhost:4566
aws sqs list-queues --endpoint-url http://localhost:4566
aws dynamodb list-tables --endpoint-url http://localhost:4566
Why dummy credentials work
Floci does not validate AWS credentials by default. Any non-empty string is accepted for AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY. The value test is used throughout this documentation as a convention, but any string works.
If you need to test SigV4 signature validation (for example, when working with Lambda, ElastiCache, or RDS IAM auth), those services do validate signatures as part of their Docker-backed implementation. The general data-plane services (S3, SQS, DynamoDB, etc.) do not.
Default account ID
Floci uses account ID 000000000000 in all ARNs and queue URLs. For example:
arn:aws:sqs:us-east-1:000000000000:my-queue
http://localhost:4566/000000000000/my-queue
FLOCI_DEFAULT_ACCOUNT_ID environment variable.
SDK configuration
Create a shared config helper and reuse it across any service client:URI endpoint = URI.create("http://localhost:4566");
AwsCredentialsProvider creds = StaticCredentialsProvider.create(
AwsBasicCredentials.create("test", "test"));
Region region = Region.US_EAST_1;
DynamoDbClient dynamo = DynamoDbClient.builder()
.endpointOverride(endpoint)
.region(region)
.credentialsProvider(creds)
.build();
SqsClient sqs = SqsClient.builder()
.endpointOverride(endpoint)
.region(region)
.credentialsProvider(creds)
.build();
Wrap the boto3 client constructor in a helper to avoid repeating connection details:import boto3
def floci_client(service):
return boto3.client(
service,
endpoint_url="http://localhost:4566",
region_name="us-east-1",
aws_access_key_id="test",
aws_secret_access_key="test",
)
s3 = floci_client("s3")
sqs = floci_client("sqs")
dynamo = floci_client("dynamodb")
Build a shared config object and pass it to each SDK client:import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { SQSClient } from "@aws-sdk/client-sqs";
import { S3Client } from "@aws-sdk/client-s3";
const config = {
endpoint: "http://localhost:4566",
region: "us-east-1",
credentials: { accessKeyId: "test", secretAccessKey: "test" },
};
const dynamo = new DynamoDBClient(config);
const sqs = new SQSClient(config);
// S3 requires forcePathStyle — Floci serves buckets at /bucket-name
const s3 = new S3Client({ ...config, forcePathStyle: true });
When using S3 with the AWS SDK v3 for Node.js, set forcePathStyle: true. Floci serves S3 in path-style mode (http://localhost:4566/bucket-name).
Load a config with a static credentials provider and a custom endpoint resolver:import (
"github.com/aws/aws-sdk-go-v2/config"
"github.com/aws/aws-sdk-go-v2/credentials"
)
cfg, err := config.LoadDefaultConfig(context.TODO(),
config.WithRegion("us-east-1"),
config.WithCredentialsProvider(
credentials.NewStaticCredentialsProvider("test", "test", ""),
),
config.WithEndpointResolverWithOptions(
aws.EndpointResolverWithOptionsFunc(
func(service, region string, opts ...interface{}) (aws.Endpoint, error) {
return aws.Endpoint{URL: "http://localhost:4566"}, nil
},
),
),
)
