← CD Wallet

Set up CD Wallet

From a new AWS account to your music playing on your phone.

This guide is for macOS and Windows and assumes you have never used AWS or a command line for development before. If you already have some of these tools, skip those steps. You will end up with an AWS account of your own, four small tools installed (Node.js, pnpm, the AWS command line and, optionally, Git), CD Wallet deployed into your account, your music uploaded and your phone paired. Expect 30 to 45 minutes, plus upload time for your library. Everything can be removed again with pnpm cdwallet destroy.

Where you type commands:

• On macOS, open Terminal (press Cmd+Space and type "Terminal").
• On Windows, open PowerShell (press the Windows key and type "PowerShell").

1. Create your AWS account

1. Go to aws.amazon.com and choose Create an AWS account. You need an email address, a credit card and a phone number. The account is usually ready in minutes but can take up to a day.
2. Sign in to the AWS console with the email and password you chose. This is the root user. It can do anything, so you use it only to set up a safer sign-in, then put it away.
3. Turn on multi-factor authentication for the root user: open the account menu (your name, top right), choose Security credentials, then Assign MFA device, and follow the prompts with an authenticator app.

Create a sign-in for your computer

Rather than create long-lived access keys that can leak, use AWS's browser sign-in (aws login), which gives your computer temporary credentials. It needs an IAM user:

1. In the console, open IAM, then Users, then Create user. Use any name, such as cdwallet-admin. Keep "Provide user access to the AWS Management Console" ticked and set a password.
2. On the permissions step, choose Attach policies directly and tick both AdministratorAccess (CD Wallet's one-time setup creates roles and a storage bucket, so it needs broad rights) and SignInLocalDevelopmentAccess (lets this user use aws login).
3. Finish creating the user and note its console sign-in URL, which looks like https://123456789012.signin.aws.amazon.com/console.
4. Sign out of the root user, sign in at that URL as the new user, and turn on MFA for it too. From now on, use this user, not root.

Signing in as the root user with aws login also works and skips these steps, but it is not recommended: a mistake or a stolen session then has no limits.

2. Install the tools

You need Node.js 22 or newer, pnpm and the AWS CLI version 2.32 or newer (older versions do not have aws login). Git is optional.

3. Get CD Wallet

With Git:

git clone https://github.com/mikemcdevitt/cd-wallet.git
cd cd-wallet

Without Git, open the GitHub page, choose Code, then Download ZIP, unzip it, and cd into the unzipped folder (for example cd ~/Downloads/cd-wallet-mainfor example cd $HOME\Downloads\cd-wallet-main).

Then install its dependencies. This takes a few minutes the first time:

pnpm install

4. Sign in to AWS

The command is the same on both systems:

aws login --profile cdwallet

The CLI asks for a region (press Enter to accept us-east-1, which the cost figures on the home page use; any region works), opens your browser, and asks you to sign in as the IAM user from step 1. Then check:

aws sts get-caller-identity --profile cdwallet

You should see your account number and the user's name. The sign-in lasts up to 12 hours; if a later command says your credentials are missing or expired, run aws login --profile cdwallet again. On a computer with no browser, or over a remote connection, add --remote.

5. Deploy

pnpm cdwallet deploy --profile cdwallet

It shows which account and region it will use and what it is about to create, and asks you to confirm. It also asks for an email address for monthly budget alerts; give one, because an alert is the only warning you get about spending. The first deploy also does AWS's one-time CDK setup in your account, so it takes a few minutes longer than later ones.

When it finishes, it saves your settings, including the admin token that allows adding and removing music, in a private file under .cdwallet in your home folder. Keep that private.

6. Import your music

Point the importer at the folder that holds your music. It reads MP3 and M4A files, skips anything else, and is safe to run again: files already uploaded are skipped.

pnpm cdwallet import ~/Music

pnpm cdwallet import "$HOME\Music"

A big library takes a while to upload, depending on your connection. If it stops partway (closed laptop, lost connection, expired sign-in), sign in again if needed and run the same command; it picks up where it left off.

7. Pair your phone

1. Install the Android app from the latest release: download the APK on your phone and open it.
2. Run pnpm cdwallet pair.
3. Scan the QR code in the app. Your library appears and you can start playing.

If something goes wrong

• aws or pnpm not found: close and reopen Terminal or PowerShell. If it still fails, run the installer again.
• aws login is not a command: your AWS CLI is older than 2.32. Check with aws --version and install the current version.
• Access denied during aws login: the IAM user is missing the SignInLocalDevelopmentAccess policy.
• OptInRequired or "service not subscribed": AWS has not finished activating the account. Complete any "Complete your AWS registration" prompt in the console, check that the account's payment method is valid and not expired, then wait a little and retry.
• "Several deployments are saved": add --name <name> to say which one you mean.
• Credentials expired during a long import: run aws login --profile cdwallet, then re-run the import.

If you are stuck, open an issue and say which system you are on and what the last command printed. Do not paste tokens or the contents of your .cdwallet folder.