Connect Tarmac to AWS SQS

Credential modes

Open the connection manager from the key icon on the left rail, or from Settings ▸ Connection ▸ Edit AWS connection. Tarmac connects with one of three credential sources.

1. AWS profile. Tarmac reads ~/.aws/config and ~/.aws/credentials and lists every profile, including default. If an SSO profile's session has expired, Tarmac says so and tells you to run aws sso login --profile <name> in a terminal. Run it, then choose Try again. Tarmac never opens the SSO browser for you.
2. Environment variables. Standard AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, plus a session token if you use one. Set them before you launch the app. Tarmac reads them at connection time.
3. AWS-compatible endpoint. A custom endpoint URL plus a static access key and secret. This is how you point Tarmac at LocalStack or another SQS-compatible service. The LocalStack preset defaults to http://localhost:4566 with test/test credentials, and payload retrieval works against LocalStack S3 too.

A connection has to pass Test connection, a live ListQueues call, before the Save button appears. On success Tarmac shows the latency in milliseconds. Saved connections reconnect on the next launch.

On launch Tarmac shows a connecting screen naming the profile and region it's using. If the connection hangs because the endpoint is unreachable or a VPN isn't up, choose Cancel. Cancel stops waiting. Tarmac will not connect you after you have cancelled.

When a saved connection fails, Tarmac shows Couldn't connect with the specific reason below the summary, such as permissions, network, or an expired session. Try again retests the same saved target. Choose a different target reopens the connection manager.

If queue loading or fetching reports expired credentials, such as an SSO session that lapsed overnight, Tarmac returns to that same screen with the reason. Refresh the session with aws sso login, then choose Try again. A live-tail fetch that fails stops the tail and reports the reason in a toast. Turn the tail back on after you reconnect.

Identity and regions

After connecting, Tarmac shows the account in the top bar as account-name (account-id). If it cannot resolve the account, the app stays connected without an identity. Glance at it before you do anything destructive. It is your guard against wrong-account mistakes.

The region switches from the top bar without re-entering credentials. Tarmac confirms first, releases the messages it is holding with the current connection, and then loads the new region's queues. Tarmac ships with 14 regions: us-east-1, us-east-2, us-west-1, us-west-2, ca-central-1, sa-east-1, eu-west-1, eu-west-2, eu-west-3, eu-central-1, ap-southeast-1, ap-southeast-2, ap-northeast-1, ap-northeast-2. AWS-compatible endpoints accept a free-text region.

IAM permissions

Follow least privilege and grant only what your workflow needs. This is what each Tarmac feature calls:

A read-only inspection setup needs only the first two rows, plus kms:Decrypt for SSE-KMS queues. You can fetch, search, and inspect with no write permissions. Every change to a queue needs its own action-specific permission.

When queue loading fails

Queue metadata loads one queue at a time, so one missing permission does not blank the whole list. If some queues fail to load, the sidebar shows a compact banner scoped to the actual damage, like "15 queues couldn't load", with a one-line diagnosis taken from the AWS error. Access denials name the missing IAM action, usually sqs:GetQueueAttributes. Deleted queues are called out as possibly removed. Network failures point at connectivity. A Details disclosure holds the error code, region, account, affected queue names, and a Copy full error action for the raw text.

Failed queues stay in the list with a warning shield. Hover it for the reason. You can still select them and browse what's cached. If the queue listing itself fails, you get Unable to load queues rather than per-queue errors, and an existing list stays visible until a later successful refresh replaces it.

Queue access

When a queue is selected, a shield sits next to its name. Its color is the whole status.

• Grey — Tarmac has not established that it can read the queue, either because the check is still running or because browsing was never confirmed.
• Green — browsing works and nothing Tarmac checked is blocked.
• Amber — something is blocking. Browsing is denied, or an operation is explicitly denied or missing an allow.

Green does not mean every permission was proven. Tarmac can only confirm what it has observed or read from your policy, and an action you have never performed on an identity whose policy it cannot read stays undetermined. Green means nothing is known to be blocked. Open the shield for the per-operation ledger, which names exactly what was confirmed and what was not.

The shield reflects your AWS permissions on that queue and nothing else. Your Tarmac plan never changes its color.

Click the chip for a compact ledger:

• This queue — browse, release, publish staged deletes, send, this queue's KMS, and redrive source when the queue is a DLQ.
• Depends on the target — destination send/KMS once you pick a destination in Queue Redrive, and S3 payload retrieval once a message points at a bucket.

Every status comes from one of two sources:

• Ready · verified — backed by an actual successful or failed operation Tarmac just performed, for example loading queue attributes. This is ground truth.
• Policy looks ready — derived from reading the queue's resource policy and your identity's policies. This is a best guess. Policy documents cannot show SCPs, permission boundaries, session policies, or condition evaluation, so a statement that looks open can still be denied at call time.

No allow found means Tarmac read the policies and did not find an Allow. Explicit denies show as Denied. An Allow statement can never override them. Unreadable or partial identity coverage stays Unknown rather than inventing a gap.

Copy missing statements copies a least-privilege Allow snippet scoped to the exact resources involved, generated only when identity coverage is complete and an action has no visible allow. Incomplete coverage, conditional statements, and runtime denials that contradict a visible allow land in an admin checklist instead. sts:GetCallerIdentity never appears; it needs no permission to call. Copy diagnostics copies the coverage summary without raw policy JSON.

In Queue Redrive, Tarmac resolves the original source queue or selected custom destination and assesses the source, destination, and KMS permissions separately. These are policy-document assessments, not permissions learned from the server-side message move.