How to Connect to DynamoDB Local and LocalStack
You have a local DynamoDB running and your code talks to it fine, but you want to
see the tables instead of writing a scan script every time. Connecting a client
to a local endpoint is two changes: point at the right URL, and hand it throwaway
credentials.
The details below are where people get stuck: region namespacing, the
alphanumeric-key rule, and the 8000 vs 4566 port split.
DynamoDB Local vs LocalStack: what you're connecting to
Both give you a DynamoDB API on localhost with no AWS account (LocalStack needs a
LocalStack account, see below), but they're different things:
- DynamoDB Local is the downloadable DynamoDB engine in a single process. AWS ships
it as a JAR and a Docker image
(
amazon/dynamodb-local). It's DynamoDB and nothing else. Default port 8000 (AWS docs). See running DynamoDB Local with Docker. - LocalStack emulates a stack of AWS services behind one endpoint. Its
DynamoDB is itself
powered by DynamoDB Local,
but every service goes through LocalStack's single
port 4566.
Since release 2026.03.0 the
localstack/localstackimage won't start without a LocalStack auth token (LOCALSTACK_AUTH_TOKEN), so you need a LocalStack account. Its free Hobby plan is for non-commercial use; commercial use needs a paid plan (pricing). If you only need DynamoDB, DynamoDB Local is free and needs no account.
So the practical difference for connecting is the endpoint URL: :8000 for
standalone DynamoDB Local, :4566 for DynamoDB-via-LocalStack. The API and the
credentials trick are the same.
To browse local tables in a grid instead of reading DynamoDB-JSON on the CLI, DynoTable connects with an Offline profile: a port and a Region, no keys to enter (setup).
Endpoint and dummy credentials
The AWS SDKs and CLI require an access key and a region even when talking to a local endpoint, but those values don't have to be real. AWS's own docs say these values "don't have to be valid AWS values to run locally" (AWS docs).
The region/access-key silently namespaces your data. Without the
-sharedDbflag, DynamoDB Local keeps a separate database per access-key ID + region, in a file namedmyaccesskeyid_region.db(AWS's exact naming).The split holds in memory too: on DynamoDB Local 3.3.1 started with
-inMemory, a table created with keyxinlocalwas invisible to keydummyinus-east-1. Connect with a different key or region than your app used and your tables look like they've vanished.The fix: start DynamoDB Local with
-sharedDb(oneshared-local-instance.dbfor every client), or use the exact key + region your app uses. On LocalStack, which keeps a separate database per credential and region too, start the container withDYNAMODB_SHARE_DB=1.The access key ID must be alphanumeric on DynamoDB Local, no symbols. AWS docs state
AWS_ACCESS_KEY_IDcan contain onlyA–Z,a–z, and0–9; AWS introduced this in DynamoDB Local 2.0.0 (and 1.23.0+), so a key with special characters that worked on an earlier image now fails (AWS re:Post). See the error below.
For LocalStack the safe default is test / test: it
ignores the secret key entirely
and never validates the secret value. Real-looking AKIA…/ASIA… keys are
rejected as a safeguard and fall back to the dummy account 000000000000,
the same account an arbitrary key like test resolves to. Stick with test.
Connecting with the AWS CLI (sanity check)
Before pointing a GUI at it, confirm the endpoint is alive from the CLI. The CLI
has no built-in default local endpoint,
so either pass --endpoint-url per command or set
AWS_ENDPOINT_URL_DYNAMODB=http://localhost:8000 (CLI v2.13+).
DynamoDB Local:
aws dynamodb list-tables --endpoint-url http://localhost:8000LocalStack (same command, different port):
aws dynamodb list-tables --endpoint-url http://localhost:4566If you have credentials configured at all (even fake ones in ~/.aws/credentials
or via AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY), this returns your table list.
An empty list with no error means the endpoint works but you're looking at a
different key/region namespace (see the gotcha above).
DynamoDB Local GUI: browsing and querying local tables in DynoTable
Once the CLI works, start the engine so every client shares one database. DynoTable signs local requests with its own fixed throwaway key, so it only sees your app's tables when the engine doesn't split them by key:
# DynamoDB Local: override the image's default command to add -sharedDb
docker run -p 8000:8000 amazon/dynamodb-local -jar DynamoDBLocal.jar -inMemory -sharedDb
# LocalStack: one shared DynamoDB database (needs your LocalStack auth token)
docker run -p 4566:4566 -e LOCALSTACK_AUTH_TOKEN=<token> -e DYNAMODB_SHARE_DB=1 localstack/localstackThen add a profile in DynoTable:
- Profile type: Offline.
- Port:
8000(DynamoDB Local) or4566(LocalStack). The profile always connects tohttp://localhost:<port>. - AWS Region: pick the region your app uses from the list, e.g.
us-east-1. On DynamoDB Local with-sharedDbany entry works; on LocalStack, match your app's region.
There is no access-key field; the profile supplies its own alphanumeric
throwaway key. From there you browse items, run a Query or Scan, and edit items
instead of marshaling JSON by hand on the CLI.
When you load fixtures, the DynamoDB-JSON converter
turns plain JSON into the wire format, and Query vs Scan
covers which read to reach for. DynoTable is local-only desktop software, so pointing
it at localhost keeps your fixtures on your machine. For a broader look at the GUI
options, see the DynamoDB GUI comparison.
Common errors (region mismatch, port, credentials)
- Connection refused. Wrong port:
8000is DynamoDB Local,4566is LocalStack. Also confirm the container actually published the port (docker run -p 8000:8000 amazon/dynamodb-local). For LocalStack, check the service is up athttp://localhost:4566/_localstack/health, and that you passedLOCALSTACK_AUTH_TOKEN: without it the container doesn't start (docker logssays why). The Access Key ID or security token is invalid.on DynamoDB Local. Since the 2.0.0 (and 1.23.0+) image, the access key ID must be alphanumeric only. A key with symbols that worked on an earlier image now fails. Replace it with letters/numbers (e.g.test) and update every tool to match.The security token included in the request is invalidagainst LocalStack. This is almost always an endpoint problem, not a credentials one: your SDK client dropped the--endpoint-url/endpoint_urland hit the real AWS endpoint, which rejects your dummy key. Confirm the client is actually pointed athttp://localhost:4566.- Credential errors from the SDK/CLI. Even local endpoints need some
credentials present. Set
AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY(or a fake profile) so the SDK's credential chain resolves. httpvshttps. DynamoDB Local speaks plainhttp, so anhttps://URL fails the TLS handshake. LocalStack accepts bothhttp://localhost:4566andhttps://localhost.localstack.cloud:4566, for which it publishes a certificate.
Is DynamoDB Local the same data as my real AWS tables?
No. Local and cloud are completely separate stores. DynamoDB Local (and LocalStack's DynamoDB) keeps data in a local file or in memory; it never touches your AWS account, and AWS Regions/accounts aren't supported at the client level locally. That's the point: it's for development and testing.
AWS suggests
valid-looking key/region values locally so your code only needs the endpoint
swapped when you move. The data stays behind: to seed a cloud table, rerun your
fixture loader against the real endpoint (BatchWriteItem, 25 items per call).
To model that schema before you ship it, single-table design and GSI vs LSI cover the decisions that don't change between local and prod.
What local saves you (and what prod still bills)
Local reports consumed capacity per request but bills nothing and never throttles; the cloud bills every read and write. When to leave Local covers what that hides. Model the jump with the pricing calculator and size representative items with the item-size calculator.
FAQ
Do I need real AWS credentials? No. Both DynamoDB Local and LocalStack accept dummy values. They just have to be present, alphanumeric (for DynamoDB Local), and consistent across your tools, unless the engine runs one shared database. LocalStack does need its own auth token to start; DynamoDB Local needs nothing.
Why do my tables disappear when I switch tools? Without -sharedDb, DynamoDB
Local keeps one database per access key + region. See
the namespacing gotcha.
What's the difference between port 8000 and 4566? 8000 is standalone
DynamoDB Local's default; 4566 is LocalStack's single port that fronts all its
emulated services, DynamoDB included.
Is DynamoDB Local free? Yes. AWS distributes DynamoDB Local at no cost as a JAR and a Docker image, with "no provisioned throughput, data storage, or data transfer costs"; it's intended for development and testing only, not production.
Can I run SQL against my local tables? Local DynamoDB speaks the same API as
the cloud, so the same access-pattern rules apply, and the same limits: DynamoDB's
PartiQL SELECT grammar
is SELECT … FROM … WHERE … ORDER BY only, with no JOIN, no GROUP BY, and
no grouping aggregate functions
like COUNT/SUM/AVG (see PartiQL vs SQL).
DynoTable's SQL Workbench runs those
analytical queries over any connection, local included.
Try DynoTable: start the engine with one shared database (-sharedDb
or DYNAMODB_SHARE_DB=1, as above), add an Offline profile on port 8000 or 4566,
and browse, query, and edit your local tables with a GUI.