FAQ and troubleshooting

Before you buy#

Can I run it as a SaaS with the Regular License?#

Only if your end users are not charged. The Envato Regular License covers one end product whose users do not pay. If studios pay you to use your deployment (subscriptions, one-off fees, any paid plan), you need the Extended License. See Envato's licence terms and Selling it as SaaS.

What are the server requirements?#

Node.js 22 (or Docker), Postgres for production, and a domain with HTTPS. As guidance, 1 vCPU and 1 GB of RAM is a comfortable start for one studio. Docker, a VPS, Railway, Render, Fly.io and Vercel all work. Full details: Requirements.

Is there a default admin login?#

No. There are no default credentials and no setup wizard. The first account created on a fresh database becomes the platform admin, so sign up yourself right after deploying. See First admin.

The demo account (demo@yourdesk.app) can sign in only when demo mode is on: with YOURDESK_DEMO=1, or in a local trial (npm run dev on localhost with no database configured). It is an ordinary studio with no admin rights, it is read-only, and its password is in the source code.

Can I host it on shared PHP or cPanel hosting?#

No. YourDesk is a Node.js application. It needs a host that runs Node 22 or Docker, or Vercel.

Do I need an AI key?#

No. Clients, projects, proposals, invoices, time and portals work without it. An xAI key adds the Agent and AI drafting; without one, drafts come from built-in templates. Only xAI is supported in 1.0.0.

Can my clients pay invoices online?#

Not in 1.0.0. Invoices show your bank details and PayPal handle, and you record payments yourself. The Stripe and PayPal integrations sell YourDesk plans, not studio invoices.

Do clients need an account?#

No. Clients use links: a portal per client, and a link per proposal and invoice. See Clients and client portals.

Is the proposal signature legally binding?#

YourDesk records a typed name, a timestamp and the browser's user-agent, and marks the proposal won. It is not a certified e-signature service. Whether that is enough for your contracts depends on where you work; ask a lawyer. Details: What a signature records.

Does it send email?#

Only through a mailbox each studio connects (Gmail, Outlook, Fastmail, iCloud or any IMAP and SMTP provider). There is no system email: no password resets, invitations or notifications. See Client updates and mail.

Can I limit features by plan?#

Not without code changes. Plans are sold and recorded, but 1.0.0 does not enforce any limits. See What a plan does.

Can I rebrand it?#

Yes, in code. Set APP_NAME and APP_TAGLINE in src/lib/brand.ts; colours, radii and fonts are tokens in src/styles.css; icons and the share image are in public/ (favicon.svg, favicon-32.png, apple-touch-icon.png, brand/, og.jpg) with public/manifest.webmanifest; the landing page is src/routes/index.tsx and src/components/marketing/. A few page titles, mostly in the Ops console, spell "YourDesk" directly, so search the source for it. The Ops → Product brand name does not rename the interface.

Is the interface translated?#

No. It is in English only in 1.0.0.

Is there a demo?#

Yes: www.yourdesk.cc, with Log in to demo account on the sign-in page. The demo desk is read-only, so you can click through everything but not save changes. You can run the same showroom yourself with YOURDESK_DEMO=1; see Demo mode.

Troubleshooting#

The server will not start: "BETTER_AUTH_SECRET is not set"#

A server running with NODE_ENV=production (the Docker image, Vercel) refuses to start without it. Generate one with openssl rand -hex 32, add it to the environment, and restart. If you are moving an existing install, use the value you had before, or stored mailbox passwords, payment keys and personal xAI keys cannot be read. See Prepare the environment.

"Invalid origin" when signing in or signing up#

Set BETTER_AUTH_URL to exactly the origin in the browser's address bar (scheme, host and port, no trailing slash), then restart. Locally, http://localhost:8080 and http://127.0.0.1:8080 are trusted without it.

I sign in, but I am signed straight back out#

• The site is on plain HTTP on an address other than localhost. Session cookies are Secure, so browsers drop them. Serve it over HTTPS.
• Everyone is signed out after every restart: BETTER_AUTH_SECRET is not set (possible only without NODE_ENV=production).
• The account was disabled in Ops → Users: sign-in shows "This account has been disabled. Contact the site operator." A platform admin can Enable it again.

"Too many requests" on the sign-in page#

Sign-in and sign-up allow 10 attempts per 15 minutes per address. If it happens to everyone at once, your proxy is not sending X-Forwarded-For, so all visitors share one limit. See HTTPS and the reverse proxy. The count resets when the app restarts.

The migration runner says "DATABASE_URL not set — skipping"#

It does not read .env. Run node --env-file=.env scripts/migrate.mjs, or export DATABASE_URL first. The same applies to the migration step at the end of npm run build:node.

Errors such as relation "…" does not exist#

The migrations have not run against this database. Run them (above), or with Docker restart the container, which migrates on start. On Vercel, make sure DATABASE_URL is available to the build.

My data disappeared after a restart or redeploy#

The app was running on the embedded database: DATABASE_URL was missing or empty. In Docker the data lived inside the container; on Vercel it lived in /tmp. Set DATABASE_URL to Postgres and run the migrations.

A feature is missing from the sidebar, or says "is turned off on this site"#

A platform admin switched it off under Ops → Product (Agent, Mail, Portals or Discover). Switch it back on there. See Configuration.

Overdue reminders are not being emailed to clients#

That is the default. They wait as drafts in Client updates until the studio owner turns on Email clients automatically under Settings → Workspace → Mailbox. Reminders drafted before that stay drafts; send them by hand. See Automatic reminders.

I signed up but there is no Ops entry#

Only the first account on a fresh database becomes platform admin. Sign in as that account and use Ops → Users → Grant Ops, or set the role in the database:

update profiles set platform_role = 'platform_admin' where email = 'you@example.com';

The app listens on port 3000#

The built Node server uses port 3000 unless PORT is set. The Docker image sets 8080, and npm run dev always uses 8080.

A Stripe payment went through but the plan did not change#

• Check that the webhook signing secret is saved in Ops → Payments → Stripe, and that the endpoint https://<your-domain>/api/payments/stripe/webhook lists checkout.session.completed, customer.subscription.updated and customer.subscription.deleted.
• In Stripe's dashboard (Developers → Webhooks), the delivery log shows the reply. "Invalid Stripe signature" means the secret belongs to a different endpoint or mode (test versus live).
• The plan must still be active in Ops → Plans with an amount above zero.

Stripe or PayPal sends customers to 127.0.0.1 after paying#

BETTER_AUTH_URL is not set. Checkout return addresses are built from it.

PayPal returns to /pricing?error=paypal#

The capture failed. Common causes: the plan's amount or currency changed after the order was created, the order was not approved, sandbox and live credentials are mixed, or the PayPal secret is missing. Check Ops → Payments → PayPal.

The mailbox refuses my password#

Gmail and Google Workspace need an App Password, not your Google password; Fastmail and iCloud need app passwords too. For "Other IMAP", use IMAP on port 993 and SMTP on 465 or 587, with public host names (IP addresses and private hosts are refused).

Saved keys or mailbox passwords stopped working after a redeploy#

BETTER_AUTH_SECRET changed (or was never set, and the fallback key file in the data folder was lost). Stored secrets are encrypted with it. Restore the old value, or enter the Stripe and PayPal keys, mailbox passwords and personal xAI keys again.

The Agent says "Add your xAI API key in Settings → Agent"#

No key was found for that user, their studio owner or the server. Add one under Settings → Agent, or set XAI_API_KEY and restart. Ops → System shows whether the server key is detected.

Uploads fail, or "Keep files under ~900KB"#

Files are limited to about 900 KB. Behind nginx, also raise client_max_body_size (its 1 MB default is too small for the largest uploads); the nginx example sets it.

Calendar import says "That link is not allowed" or "Use an https link"#

The link must be https:// on the standard port with a public domain name. IP addresses, localhost and internal names are refused, as are calendars over 1 MB or slower than 10 seconds. Download the .ics file and use Upload .ics instead.

The share image does not appear in link previews#

VITE_PUBLIC_HOSTNAME is compiled in at build time. Set it before building, and for Docker pass it as a build argument; see Share card hostname in Docker builds.