I Stopped Using LocalStack. Here’s What I Use Instead. Floci!

If you’ve built anything on AWS, you know the pain.

You want to test a Lambda that drops a message into SQS. Or an S3 upload pipeline. Or a quick DynamoDB read. And every time, you face the same three bad choices:

1. Deploy to a real AWS dev account
2. Run LocalStack
3. Mock everything in code

So a few weeks back I was trying to debug a small SQS issue on my laptop. Nothing complex — just a producer pushing messages and a consumer reading them. Normal stuff. But my LocalStack container was eating around 1.5–2 GB of RAM, my fan was screaming, and the startup took long enough that I went to make coffee while waiting.

I remember thinking — this is way too much machinery for what I’m actually doing.

That’s when I went hunting for alternatives and found Floci.

It’s tiny. It works. And honestly I haven’t gone back to LocalStack for day-to-day work since. So I figured I’d write down how I have it set up, in case it’s useful for anyone else feeling the same friction.

What Floci actually is?

It’s an AWS emulator that runs in a single Docker container. Same idea as LocalStack — you point your AWS SDK at localhost:4566 instead of the real AWS endpoint and it pretends to be S3, SQS, SNS, DynamoDB, etc.

It doesn’t try to do everything. It doesn’t have a slick web UI. It just does the common services well, in a small container, with no paid tier creeping in.

Links if you want to poke around:

• GitHub → https://github.com/floci-io/floci
• Docker Hub → https://hub.docker.com/r/hectorvent/floci

A heads up before we start — Floci doesn’t cover every AWS service. If you need Step Functions or Cognito or some niche integration, this isn’t for you. But if 90% of your work is queues, buckets, topics, and tables (and let’s be honest, it usually is), you’ll like it.

What you need

Just Docker and the AWS CLI. That’s it.

docker --version
aws --version

If both of those return something, you’re good. Five minutes of setup, tops.

Getting Floci running

Pull the image:

docker pull hectorvent/floci:latest

Then run it:

docker run -d -p 4566:4566 --name floci hectorvent/floci:latest

The flags, in case you’re new to Docker:

• -d runs it in the background
• -p 4566:4566 maps port 4566 inside the container to port 4566 on your machine
• --name floci is just so you don't have to deal with the random "wonderful_einstein" names Docker gives you

Check it’s actually running:

docker ps

You should see something like this:

CONTAINER ID   IMAGE                      STATUS         PORTS                    NAMES
e2e1c3645983   hectorvent/floci:latest    Up X minutes   0.0.0.0:4566->4566/tcp   floci

If something looks off, docker logs floci will usually tell you what's wrong.

Make your life easier with an alias

Talking to Floci is just running AWS CLI commands with --endpoint-url=http://localhost:4566 tacked on. Doable, but you'll get tired of typing that pretty quickly.

Open your shell config — ~/.bashrc for bash, ~/.zshrc for zsh — and add this at the bottom:

# Floci / Local AWS
export AWS_DEFAULT_REGION=us-east-1
export AWS_ACCESS_KEY_ID=test
export AWS_SECRET_ACCESS_KEY=test

alias awslocal='aws --endpoint-url=http://localhost:4566'

A couple of things worth knowing:

The access key and secret are dummy values. Floci doesn’t care what they are but the AWS CLI refuses to run without some credentials in place. So we feed it junk.

The alias name awslocal is the same one LocalStack uses. If you're coming from LocalStack, your muscle memory will keep working.

Reload your shell:

source ~/.bashrc

Now awslocal s3 ls works the same way aws s3 ls does against real AWS.

Trying it out — SQS

Let’s create a queue:

awslocal sqs create-queue --queue-name test-queue

You’ll get back something like:

{
    "QueueUrl": "http://localhost:4566/000000000000/test-queue"
}

The 000000000000 is a dummy account ID. Same convention LocalStack uses.

Send a message:

awslocal sqs send-message \
  --queue-url http://localhost:4566/000000000000/test-queue \
  --message-body "Hello from Floci"

Read it back:

awslocal sqs receive-message \
  --queue-url http://localhost:4566/000000000000/test-queue

You’ll see the message body and a ReceiptHandle. Use that handle to delete it:

awslocal sqs delete-message \
  --queue-url http://localhost:4566/000000000000/test-queue \
  --receipt-handle "PASTE_RECEIPT_HANDLE_HERE"

And to nuke the queue when you’re done:

awslocal sqs delete-queue \
  --queue-url http://localhost:4566/000000000000/test-queue

That’s it. Same commands you’d run against real AWS, just hitting localhost.

S3

awslocal s3 mb s3://my-test-bucket

Upload something:

echo "Hello Floci S3" > /tmp/testfile.txt
awslocal s3 cp /tmp/testfile.txt s3://my-test-bucket/testfile.txt

List:

awslocal s3 ls s3://my-test-bucket/

Pull it back:

awslocal s3 cp s3://my-test-bucket/testfile.txt /tmp/downloaded.txt
cat /tmp/downloaded.txt

Cleanup:

awslocal s3 rm s3://my-test-bucket/testfile.txt
awslocal s3 rb s3://my-test-bucket

Nothing surprising. Which is the point.

SNS

awslocal sns create-topic --name test-topic

awslocal sns publish \
  --topic-arn arn:aws:sns:us-east-1:000000000000:test-topic \
  --message "Hello from Floci SNS"

awslocal sns delete-topic \
  --topic-arn arn:aws:sns:us-east-1:000000000000:test-topic

Where SNS gets actually useful locally is when you subscribe a queue to a topic and test fan-out flows. That’s where mocks fall apart… they can’t replicate the SNS-to-SQS delivery quirks. Floci handles it.

DynamoDB

Create a table:

awslocal dynamodb create-table \
  --table-name test-table \
  --attribute-definitions AttributeName=id,AttributeType=S \
  --key-schema AttributeName=id,KeyType=HASH \
  --billing-mode PAY_PER_REQUEST

Put an item:

awslocal dynamodb put-item \
  --table-name test-table \
  --item '{"id": {"S": "001"}, "name": {"S": "Sahil"}, "role": {"S": "Developer"}}'

Read it:

awslocal dynamodb get-item \
  --table-name test-table \
  --key '{"id": {"S": "001"}}'

Scan everything:

awslocal dynamodb scan --table-name test-table

Clean up:

awslocal dynamodb delete-table --table-name test-table

A small health check script I keep around

I made this script so I can quickly confirm Floci is working before I start a debugging session. Nothing fancy just hits each service, succeeds or fails, and tells you.

Save it as ~/floci_healthcheck.sh:

#!/bin/bash
echo "========================================="
echo "  Floci Health Check"
echo "========================================="
echo ""
echo "[1] Checking Docker container..."
if docker ps | grep -q floci; then
    echo "    ✓ Floci container is running"
else
    echo "    ✗ Floci container is NOT running"
    echo "    Run: docker start floci"
    exit 1
fi
echo ""
echo "[2] Testing SQS..."
SQS_RESULT=$(awslocal sqs create-queue --queue-name healthcheck-queue 2>&1)
if echo "$SQS_RESULT" | grep -q "QueueUrl"; then
    echo "    ✓ SQS is working"
    awslocal sqs delete-queue --queue-url http://localhost:4566/000000000000/healthcheck-queue 2>/dev/null
else
    echo "    ✗ SQS failed: $SQS_RESULT"
fi
echo ""
echo "[3] Testing S3..."
S3_RESULT=$(awslocal s3 mb s3://healthcheck-bucket 2>&1)
if echo "$S3_RESULT" | grep -q "make_bucket"; then
    echo "    ✓ S3 is working"
    awslocal s3 rb s3://healthcheck-bucket 2>/dev/null
else
    echo "    ✗ S3 failed: $S3_RESULT"
fi
echo ""
echo "[4] Testing SNS..."
SNS_RESULT=$(awslocal sns create-topic --name healthcheck-topic 2>&1)
if echo "$SNS_RESULT" | grep -q "TopicArn"; then
    echo "    ✓ SNS is working"
    awslocal sns delete-topic --topic-arn arn:aws:sns:us-east-1:000000000000:healthcheck-topic 2>/dev/null
else
    echo "    ✗ SNS failed: $SNS_RESULT"
fi
echo ""
echo "[5] Testing DynamoDB..."
DDB_RESULT=$(awslocal dynamodb list-tables 2>&1)
if echo "$DDB_RESULT" | grep -q "TableNames"; then
    echo "    ✓ DynamoDB is working"
else
    echo "    ✗ DynamoDB failed: $DDB_RESULT"
fi
echo ""
echo "========================================="
echo "  Health Check Complete"
echo "========================================="

Make it executable and run:

chmod +x ~/floci_healthcheck.sh
~/floci_healthcheck.sh

If you see four ticks, you’re good to go.

Docker commands I end up using

Nothing here is Floci-specific really, but if you’re not living in Docker every day these come up:

docker start floci          # start it back up
docker stop floci           # stop it
docker restart floci        # if something's acting weird
docker logs floci           # see what it's doing
docker logs -f floci        # follow logs live
docker rm -f floci          # nuke it

I tend to just leave Floci running in the background. It uses so little memory it’s not worth stopping.

When things go wrong

A few issues I’ve hit:

“Could not connect to the endpoint URL” -> usually means the container isn’t running. docker ps will confirm. If it's not there, docker start floci.

“Unable to locate credentials” -> your shell config didn’t load. Either run source ~/.bashrc or restart your terminal. Worst case, aws configure and put test for both fields.

Port conflict -> if you’ve got LocalStack running on the same port, either stop it or run Floci on a different port:

docker run -d -p 4567:4566 --name floci hectorvent/floci:latest

Then update your alias to point at 4567 instead.

A service returns weird errors -> Floci doesn’t support everything. Check the GitHub repo for the current list of supported services before assuming something’s broken.

So should you switch?

Honestly, depends on what you’re doing.

If you’re using LocalStack for the basics — SQS, S3, SNS, DynamoDB — Floci is just lighter and faster. Less RAM, less waiting, no Pro tier nagging you. I switched and never looked back.

If you’re testing Step Functions, IAM policy edge cases, or some service Floci doesn’t emulate yet, stick with LocalStack. Right tool for the right job.

For me, day-to-day local development on AWS-backed services is just Floci now. I open my laptop, the container is already running, and I never think about it.

That’s kind of the highest praise I can give a developer tool that I stopped noticing it.

If you give it a shot, let me know how it goes in the comments. Especially if you hit something I missed — always curious where the edges are.

Links one more time:

• GitHub → https://github.com/floci-io/floci
• Docker Hub → https://hub.docker.com/r/hectorvent/floci