Quickstart

This walks you from an empty server to a sent invoice. Each step names the exact buttons in the app.

1. Install Consultainer

   On a server with Docker:

   curl -O https://raw.githubusercontent.com/Armistice-Group/retainer/main/docker-compose.yml
   curl -o .env https://raw.githubusercontent.com/Armistice-Group/retainer/main/.env.example

   Copy

   Open .env and fill in the Required section:

   openssl rand -base64 32   # paste as AUTH_SECRET
   openssl rand -base64 32   # paste as INTEGRATION_ENCRYPTION_KEY (keep a copy somewhere safe)
   openssl rand -hex 32      # paste as CRON_SECRET

   Copy

   Also change POSTGRES_PASSWORD, and if the server is reachable from the internet, set SETUP_TOKEN (openssl rand -hex 16). Then:

   docker compose up -d

   Copy

   Self-hosting explains every setting, HTTPS with a domain, backups and upgrades.

2. Create your workspace

   Open http://<your-server>:3113. A new install sends you to /setup. Enter the Setup token (if you set one), your Organization name, the Instance URL people will use to reach the app, and your name, email and password. Click Create workspace.

   You're now the organization's Owner, and you land on a checklist of next steps. It stays available at /welcome.

3. Set your organization defaults

   Go to Settings → General. In the Organization card, check:

   • Invoice number prefix, Default currency, Default tax rate (%) and Default payment terms (Net 30 unless you change it). New clients and invoices start from these.
   • Default bill rate: what you charge per hour, in your default currency. People start at this rate when they're put on a project (you can give someone their own rate on Settings → Members).
   • Timesheet approval: Off, Contractors, or Everyone except admins. When on, covered people submit each week from Time, and their time can't be invoiced until an admin approves it.
   • Expense approval threshold: members' expenses above this need approval before they can be invoiced.

   Click Save changes. On the right, under Logo & branding, upload your logo; it appears on invoice PDFs and share pages.

   Then go to Settings → Payments and, under Payment methods, add how clients can pay you (ACH, wire, a payment link…). They're shown on invoices. See Payments to take card and ACH payments online.

4. Invite your team

   Go to Settings → Members and click Invite member. Enter their email, choose Member or Admin, and click Create invite. Copy the link and send it to them (it's also emailed if email is set up). They set a name and password and they're in.

   In the member list, fill in each person's Cost (what an hour of their time costs you) so Reports can show profit.

   To make everyone use an authenticator app, set one up on your own Profile, then tick Require two-factor authentication under Settings → Security. If someone forgets their password, they can use Forgot password? on the login page, or you can make them a reset link from the ⋯ menu on Settings → Members.

   Prefer single sign-on? Set it up under Settings → Security instead; see Team & security for what each role can do and step-by-step SSO setup for Google Workspace, Microsoft Entra ID and Okta.

5. Add your first client

   Go to Clients and click Add client. Enter the Company name and, under billing, a Billing email and Payment terms if they differ from your defaults. Click Create client.

   On the client's page, click Add contact for the people you work with. Tick Send invoices to this person for whoever should receive invoices.

   Have many clients already? Clients → Import takes a CSV.

6. Create a project and set bill rates

   On the client's page, click New project (or Projects → New project). Enter a Project name, pick a Billing type:

   • Hourly: billed from logged time.
   • Flat fee: a fixed Flat fee amount for the engagement.
   • Milestone-based: billed per deliverable as milestones are completed.

   Optionally set Budget (hours) to get alerts at 80% and 100%. Click Create project.

   On the project page, in Team & bill rates, click Add team member, pick a person, check their Hourly rate (it's filled in from their default rate), and click Add to project. Do this for everyone who will log time here.

   Billable time is invoiced at the person's rate on the project. If you're the only person in the organization, you're added to new projects automatically at your default rate. Set your default rate first (Default bill rate on Settings → General, or your own Rate on Settings → Members); with neither set you start at $0/hr, and you'd need to click the pencil next to your rate on each project before you invoice.

7. Log time

   Go to Time and click Log time. Choose the Project, the Date and Hours, add a Description of the work, keep Billable ticked, and click Log time. On the invoice, time is grouped into one line per project and person at their rate.

   You can also start a timer from any task, connect your calendar so meetings become time entries, or log time from an AI agent over MCP. See Time tracking.

8. Create your first invoice

   Go to Invoices and click New invoice. Pick the client. You see everything ready to bill: unbilled billable time, completed milestones and approved expenses. Tick what to include, check Issue date, Payment terms and Due date, and click Generate invoice.

   The draft opens. Check the line items; you can edit them, or add a manual line, while it's a draft.

9. Send it

   With email set up, click Email to client, check the recipients, add an optional message, and click Send invoice. The client gets a link to view, download and pay it, the invoice is marked as sent, and you're alerted when they open it. (Owners and admins can email invoices.)

   Without email, click Mark as sent, then Copy client link and send the link yourself. Opens are still tracked.

   When the money arrives, click Mark as paid (or let Stripe or Mercury do it for you).

Check it worked

• Invoices lists your invoice as Sent.
• The time entries you invoiced show as billed on Time and can no longer be edited.
• Dashboard shows your outstanding balance.

Next steps