Skip to content

First run & login

On first start the server generates a password, and everything except a tiny public allowlist requires it — here's how to log in and open your first session.

The generated password

The password lives in a config file at ~/.config/painapple-code/config.yaml (mode 0600, parent dir 0700; inside the Docker container that's under /home/app/):

password: <generated-token>

Every start logs a login URL with the password embedded as ?tkn=… — on the very first run it's flagged as newly generated:

Auth config generated at ~/.config/painapple-code/config.yaml. Log in once via: http://127.0.0.1:8765/?tkn=…

Open that URL once in your browser and you're in.

Reveal the password later

awk '/^password:/ {print $2}' ~/.config/painapple-code/config.yaml

Running in a container? The built-in CLI prints the full login URL:

painapple docker password
# or, without the CLI:
docker exec painapple-code awk '/^password:/ {print $2}' \
    /home/app/.config/painapple-code/config.yaml

Rotate the password

Delete the config file and restart — a new password is generated on the next start:

rm ~/.config/painapple-code/config.yaml
# then restart the server and grab the new login URL from the logs

How auth works

Three auth paths are accepted:

Path Works for Notes
Cookie bridge_auth=<HMAC-derived-token> HTTP + WebSocket Set automatically after your first login; lasts 30 days
Query ?tkn=<password> HTTP + WebSocket On HTTP, the middleware issues a Set-Cookie (and redirects HTML pages to strip the token from the URL), so follow-up requests don't need it
Header Authorization: Bearer <password> HTTP only For curl and scripts

So in practice: open the login URL once, the cookie takes over, and you stay logged in. If you land on a page without auth, you're redirected to /login, where you can paste the password instead.

# Scripting example
curl -H "Authorization: Bearer $(awk '/^password:/ {print $2}' ~/.config/painapple-code/config.yaml)" \
    http://localhost:8765/api/welcome/projects

/health needs no auth

GET /health is on the public allowlist (along with the login page and PWA manifest), so liveness checks and monitoring work without a token:

curl http://localhost:8765/health

Your first session

  1. Open the app. Go to http://localhost:8765/ (redirects to /app) — or just use the login URL from the logs, which lands you there authenticated.
  2. Welcome screen. A fresh install greets you with the welcome tab: once you have history it lists recent sessions grouped by project, plus the projects in your workspace. For now, start a new session.
  3. Pick a directory. Choose the project directory Claude should work in — sessions are bound to a working directory inside your workspace.
  4. Send a prompt. Type into the input box and hit Enter. The bridge spawns a Claude Code subprocess for the session and streams the response — tool calls, thinking blocks and all — into the chat.

Install the PWA

On iPad (or any browser), install the app to your home screen on first visit — the auth cookie persists, so subsequent launches go straight to your sessions.

Next steps