← Back to Aster

Phone access · Setup guide

Set up Aster on your phone

Your phone opens an SSH server’s projects through a relay you deploy yourself, so it keeps working while your Mac is off. It takes about ten minutes, once.

What you need

  • RequiredAster 1.0.6 or later on your Mac, with at least one SSH server added.
  • RequiredA free Cloudflare account. You don’t need to add a payment method.
  • RequiredGit and Node.js on the computer you deploy the relay from.
  • RequiredA phone with a current browser. The steps below use an iPhone and Safari.

  1. Deploy your relay

    Create a Cloudflare account without adding a payment method. Then get the relay from the Aster source and deploy it to the Workers Free plan:

    Terminal
    git clone --depth 1 https://github.com/rkdrn79/aster.git
cd aster/relay
npm install
npx wrangler login
npm run deploy                       # prints https://aster-relay.<subdomain>.workers.dev
mkdir -p ~/.config/aster-relay
node -e "process.stdout.write(require('crypto').randomBytes(32).toString('base64url'))" > ~/.config/aster-relay/relay-key
chmod 600 ~/.config/aster-relay/relay-key
npx wrangler secret put RELAY_KEY < ~/.config/aster-relay/relay-key
curl https://aster-relay.<subdomain>.workers.dev/health   # {"status":"ok"}
echo "wss://aster-relay.<subdomain>.workers.dev/ws?key=$(cat ~/.config/aster-relay/relay-key)"

    Replace <subdomain> with the one npm run deploy printed. The last line prints your relay URL; you paste it into Aster in the next step.

    Idle connections hibernate and keepalive pings are free, so personal use stays within the free plan. Without a payment method, going over the free daily limits makes the relay refuse requests until 00:00 UTC; it never charges you.

  2. Turn it on in Aster

    In Aster, open Research → Home and choose Phone. If you skipped the step above, Open setup in a terminal deploys the relay for you and fills in its URL. Paste the relay URL once, then choose Turn on for each SSH server you want on your phone. The server keeps the setting and rejoins the relay after a restart, without your Mac.

    If a server runs an older Aster, the dialog says so; update it under Settings → SSH and try again. On a host without the desktop app, aster serve --relay '<relay URL>' prints the same QR code in the terminal.

  3. Scan the QR code

    Choose Phone QR next to the server. Scan the code with the phone’s camera and open the link in Safari. Aster opens on that server’s projects.

  4. Add Aster to the Home Screen

    In Safari, tap Share → Add to Home Screen. Aster gets its own icon and opens full screen, with tabs for Home, Agents, Runs and Files.

  5. Paste the link once in the Home Screen app

    Open Aster from the Home Screen. It doesn’t share Safari’s storage, so the first time it shows Connect to Aster. Paste the pairing link into Pairing URL or code and tap Connect. After that it opens straight to your server.

    To get the link onto the phone, use Copy link for the Home Screen app on the card Aster shows on its Home page in Safari, right after you scanned the QR code. Or choose Copy link in Aster’s Phone dialog on your Mac; with Universal Clipboard, an iPhone signed in to the same Apple ID can paste it.

  6. Turn on notifications

    In the Home Screen app, open the ⋯ menu and turn on Notify me, then allow notifications. Your phone tells you when an agent needs you or a Run finishes or fails, even with the app closed. This needs iOS 16.4 or later.

Keep the link and the relay URL private

The pairing link is a credential. Anyone with the link or the QR code can open that server’s projects, agents and terminals from their own browser. Don’t post it, share a screenshot of it, or paste it into an issue.

  • Choosing Phone QR again makes a new code and retires the last one. Do that if a link leaks.
  • Keep the relay URL private too: its key keeps others off your relay and your free quota. To change the key, run npx wrangler secret put RELAY_KEY with a new one and paste the new URL into Aster.
  • Turn off in the Phone dialog stops phone access to that server.
  • The relay only forwards end-to-end encrypted frames and never sees your files or terminals in plain text.

Good to know

  • Phone access is experimental.
  • It covers SSH servers and hosts that run aster serve --relay. Projects that live only on your Mac don’t appear on the phone.
  • On the phone you get Home (with deadlines and the GPU queue), Agents with the same chat as on your Mac, Runs and Experiments, and Files, including the project’s papers. Experiment notebooks, Compare and the Library page stay in the desktop app.
  • Each server row in the Phone dialog lists its paired phones. Revoke cuts one off if a link leaks or you change phones.
  • There is no native app. The phone loads the Aster web client from this site and talks to your server only through your relay.
  • More detail, including the relay source and its changes, is in relay/README.md.