# Marula PSA documentation — v0.3 > Marula PSA documentation, version v0.3. > Licensed CC BY 4.0: https://creativecommons.org/licenses/by/4.0/ > Trademarks: the Marula name and logo are trademarks; the licence grants no trademark rights. > Source: https://github.com/marulahq/marula-core/tree/main/docs/site Canonical index: https://getmarula.com/docs/psa/v0.3 Full text: https://getmarula.com/docs/psa/v0.3/llms-full.txt Machine manifest: https://getmarula.com/docs/manifest.json ## Home - [Marula documentation](https://getmarula.com/docs/psa/v0.3) — Marula is an open-source PSA (professional services automation) platform for IT service teams and MSPs. ## Start here - [Start here](https://getmarula.com/docs/psa/v0.3/start) — Pick the row that matches your job. Each page lists tasks in the words people actually use ("a customer cannot log in", "I need to close the month") and… - [Owner tasks](https://getmarula.com/docs/psa/v0.3/start/owners) — You are accountable for the numbers and for who can see what. These are the jobs that land on your desk, in the order they usually arrive. - [Admin tasks](https://getmarula.com/docs/psa/v0.3/start/admins) — Most of this work happens once, at the start, and then twice a year. The list is grouped by the job rather than by the settings menu, because the menu moves… - [Technician tasks](https://getmarula.com/docs/psa/v0.3/start/technicians) — The technician's path through Marula: work the queue, run a service day, log billable time and answer the customer. - [Operator tasks](https://getmarula.com/docs/psa/v0.3/start/operators) — You are not the workspace admin. Admins configure boards, email routing and people. - [Agent and automation tasks](https://getmarula.com/docs/psa/v0.3/start/agents) — Marula separates three things that are easy to blur: what an agent may do (grants), what it did (provenance and audit), and what the platform exposes (API… - [Admin how-to guides](https://getmarula.com/docs/psa/v0.3/how-to) — Each how-to guide gives you a direct checklist for one specific job in Marula. If you are brand new and want a guided walkthrough from start to finish… ## Tutorials - [Tutorials](https://getmarula.com/docs/psa/v0.3/tutorials) — Each tutorial walks you through one real job from start to finish using the sample organization that ships with Marula. - [Tutorial: your first ticket (in the UI)](https://getmarula.com/docs/psa/v0.3/tutorials/first-ticket) — When a client calls or emails with a problem, you shouldn't have to bounce between a ticket tab, a separate stopwatch popup, and a timecard sheet at 5 PM. - [Tutorial: your first invoice](https://getmarula.com/docs/psa/v0.3/tutorials/first-invoice) — Walk the invoice cycle end to end in the demo organization, from billable time to a sent invoice. - [Tutorial: your first inventory sync](https://getmarula.com/docs/psa/v0.3/tutorials/first-inventory-sync) — When you pull computers and network gear from an RMM tool, an MDM, and a spreadsheet, most PSAs dump duplicate rows into your asset list and leave techs… - [Tutorial: your first agent run](https://getmarula.com/docs/psa/v0.3/tutorials/first-agent-run) — In many tools, turning on AI means letting a bot rewrite tickets or email clients behind your back. - [Tutorial: portal onboarding](https://getmarula.com/docs/psa/v0.3/tutorials/portal-onboarding) — Your clients shouldn't have to email your helpdesk just to check if a ticket is being worked on, download last month's invoice, or approve a hardware quote. - [Tutorial: your first ticket](https://getmarula.com/docs/psa/v0.3/tutorials/first-ticket-api) — If you prefer exploring a system from the terminal or want to build an integration script, this tutorial walks through the exact same workflow as Your first… ## Set up and administer - [How to bootstrap your first organization](https://getmarula.com/docs/psa/v0.3/how-to/admin-org-bootstrap) — When you launch a fresh Marula install, you create your organization and first administrator account right from the sign-in screen. - [How to manage users and invites](https://getmarula.com/docs/psa/v0.3/how-to/admin-users-invites) — Instead of creating temporary passwords and reading them over the phone, you invite teammates from Settings → Team. - [How to connect an IdP (SSO)](https://getmarula.com/docs/psa/v0.3/how-to/admin-sso) — Single Sign-On (SSO) lets your staff sign in to Marula through your company's identity provider (such as Google Workspace, Microsoft Entra ID, Okta, or… - [How to configure email](https://getmarula.com/docs/psa/v0.3/how-to/admin-email) — This page covers three jobs in order: routing inbound mail to boards, proving your domain with DNS, and choosing how outbound mail leaves. - [How to configure SLA calendars & escalation ladders](https://getmarula.com/docs/psa/v0.3/how-to/admin-sla-calendars) — When a client has an agreement for a 2-hour response on urgent tickets, you don't want the SLA clock ticking at 3 AM on a Sunday unless they pay for 24/7… - [How to set workflow categories](https://getmarula.com/docs/psa/v0.3/how-to/admin-workflow-categories) — In many ticketing tools, renaming a board column from "Waiting on Vendor" to "Parts Ordered" breaks every SLA rule, report filter, and billing script that… - [How to author automation rules](https://getmarula.com/docs/psa/v0.3/how-to/admin-automation-rules) — Automation rules let your service desk handle repetitive routing and follow-ups automatically: for example, alerting a manager when a P1 ticket arrives… - [How to set up labels and label templates](https://getmarula.com/docs/psa/v0.3/how-to/admin-labels) — A template is typed by PURPOSE, and the purpose decides which fields it can print and what its QR code points at. Four purposes ship: - [How to run a dry-run import](https://getmarula.com/docs/psa/v0.3/how-to/admin-imports) — Moving clients, contacts, tickets, or hardware assets from a legacy PSA or spreadsheet shouldn't be a blind leap of faith. - [How to manage dashboards & report schedules](https://getmarula.com/docs/psa/v0.3/how-to/admin-dashboards-reports) — Marula gives service leads and owners three ways to track how the shop is running: live Dashboards (/reports/dashboards), a custom Report Builder… - [How to set up CSAT surveys on resolution](https://getmarula.com/docs/psa/v0.3/how-to/admin-csat-surveys) — Set up satisfaction surveys on ticket resolution, with intervals, link validity and quiet hours. - [How to set up toolboxes and dispatch defaults](https://getmarula.com/docs/psa/v0.3/how-to/admin-toolboxes) — Settings → Toolboxes & day pack is the config home for toolboxes. It holds the kits themselves, the tools inside them, the mappings the day pack reads, and… - [How to use reply snippets](https://getmarula.com/docs/psa/v0.3/how-to/admin-reply-snippets) — A reply snippet is a canned reply your team writes once and inserts everywhere. Open the composer on any ticket, press Snippets, and pick one. - [How to buy: vendors, purchase orders, receiving, bills](https://getmarula.com/docs/psa/v0.3/how-to/admin-purchasing) — Purchasing lives at Purchasing (/purchasing). A purchase order is the paper trail from "we need this" to "it is on the shelf and the bill is posted"… ## Tickets, time and field work - [How to work a ticket](https://getmarula.com/docs/psa/v0.3/how-to/staff-work-a-ticket) — Working a ticket in Marula happens on one screen so you don't lose your place switching between notes, your stopwatch, and client documentation. - [How to log billable time with categories](https://getmarula.com/docs/psa/v0.3/how-to/staff-time-categories) — How work categories decide what a time entry bills, where it lands and why the category matters. - [How to work a day pack](https://getmarula.com/docs/psa/v0.3/how-to/staff-day-pack) — The day pack is the trip preparation panel at the top of Today. It answers three questions before you leave. - [How to use multiple windows](https://getmarula.com/docs/psa/v0.3/how-to/staff-multi-window) — How to open a second window on the same work, with a compact shell and the workbar. - [How to use the keyboard shortcuts](https://getmarula.com/docs/psa/v0.3/how-to/staff-keyboard-shortcuts) — You can navigate boards, create tickets, copy record links, and search across Marula without taking your hands off the keyboard. - [How to use Marula with a keyboard, a screen reader, and themes](https://getmarula.com/docs/psa/v0.3/how-to/staff-accessibility) — Marula is built to be usable without a mouse. You can run a ticket from the keyboard end to end, hear what changes through a screen reader, and pick a theme… - [How to sign your own email](https://getmarula.com/docs/psa/v0.3/how-to/staff-email-signature) — Every message you send to a client can close with your own details: your name, your address, the workspace name. - [How to scan barcodes and QR codes](https://getmarula.com/docs/psa/v0.3/how-to/staff-scanning) — How a scan resolves to one typed record — ticket, asset or stock item — before Marula acts on it. - [How to run stock and use parts](https://getmarula.com/docs/psa/v0.3/how-to/staff-stock-and-parts) — Stock lives at Stock (/stock). The board reads the same on-hand rows the low-stock alerts use, so the numbers you see here are the numbers automations act on. - [How to check tools out, and how to run client loans](https://getmarula.com/docs/psa/v0.3/how-to/staff-tools-and-loans) — Tools are stock items flagged as tools: serialized, individually tracked, and always answerable to "who has this unit right now". - [How to dispatch from the board](https://getmarula.com/docs/psa/v0.3/how-to/staff-dispatch) — The Dispatch board (/dispatch) gives dispatchers and technicians a single view of who is booked where, which tickets are waiting for an owner, and how much… - [Turn on travel time and mileage reconciliation](https://getmarula.com/docs/psa/v0.3/how-to/admin-routing-travel) — This guide configures a routing provider, sets a technician's day start, reads the travel warnings the dispatcher sees, and reconciles logged mileage into… - [How to run a service day from the phone](https://getmarula.com/docs/psa/v0.3/how-to/technician-service-day) — Today is the first screen after sign-in. It reads the same dispatch board the office sees, narrowed to your bookings: - [How to move stock and check out tools in the field](https://getmarula.com/docs/psa/v0.3/how-to/technician-field-ops) — The phone moves stock through the same ledger as the web app. A transfer you make in a basement and a transfer the stockroom makes at the desk are the same… - [How to use the Marula mobile app](https://getmarula.com/docs/psa/v0.3/how-to/technician-mobile-app) — The mobile app is the same product as the web app against the same API. A note you write on the phone lands on the ticket everyone else is looking at, and a… - [How to check out tools and use parts on site](https://getmarula.com/docs/psa/v0.3/how-to/technician-tools-and-parts) — Your day pack lists what the jobs need: the tools, the consumables, and the parts already reserved against the tickets. It lives on Today under the schedule. ## Billing and contracts - [How to bill project work — contracts, milestones, fees](https://getmarula.com/docs/psa/v0.3/how-to/project-billing) — A ticket traces work to a client. But rollout projects and migrations live in Projects — and until now, project work that skipped tickets had no path to an… - [How to verify a billing period before you invoice it](https://getmarula.com/docs/psa/v0.3/how-to/admin-billing-verification) — An invoice run prices what it finds. Verification is where a human reads that same window first, decides what each entry really is, lowers the ones that… - [How to price a service contract](https://getmarula.com/docs/psa/v0.3/how-to/admin-contract-types) — A contract is one client's answer to how do we get paid for this work? The type you pick decides what the engine evaluates. - [How to record FX rates & read reconciliation](https://getmarula.com/docs/psa/v0.3/how-to/admin-fx-rates) — If your MSP bills a client in EUR or CAD while reporting company financials in USD, you need historical invoices and inventory receipts to keep the exact… ## Client portal - [How to set up the portal](https://getmarula.com/docs/psa/v0.3/how-to/admin-portal-setup) — The Client Portal lets your customers submit support requests, view their invoices, read client-facing help articles, and book appointment slots without… - [How to use the portal (client-side tasks)](https://getmarula.com/docs/psa/v0.3/how-to/client-portal-tasks) — The Client Portal gives you a single place to open support requests, check the status of ongoing work, review invoices, read help guides written for your… - [How to approve or decline a quote](https://getmarula.com/docs/psa/v0.3/how-to/client-quote-approval) — How a client reads, accepts or declines a quote in the portal, and what changes after acceptance. ## Automation, API and agents - [How to call the API](https://getmarula.com/docs/psa/v0.3/how-to/call-the-api) — Every action in the Marula web app, desktop app, and mobile app goes through the same /api/v1/… REST API. - [How to report against the read model](https://getmarula.com/docs/psa/v0.3/how-to/read-model) — Because you own your PostgreSQL database, you can connect Metabase, Grafana, Power BI, or psql directly to Marula for custom reporting. - [How to manage API keys](https://getmarula.com/docs/psa/v0.3/how-to/admin-api-keys) — When an external script, monitoring tool, or custom integration needs to call Marula's API without a human signing in, you issue a scoped API key under… - [How to bring up AI with your own API keys](https://getmarula.com/docs/psa/v0.3/how-to/admin-ai-bringup) — Six settings decisions, in a fixed order, all on Settings → AI. The cards on that page sit in the order of the steps below. - [How to manage AI access](https://getmarula.com/docs/psa/v0.3/how-to/admin-ai-access) — Marula treats AI as an optional tool that you control down to each role and screen. - [How to run transcription and embeddings on your own hardware](https://getmarula.com/docs/psa/v0.3/how-to/admin-local-ai-models) — Marula will call a model runtime you run. The image you already deploy carries no model weights, so the models are a separate opt-in step: start the local… - [How to extend Marula with plugin surfaces](https://getmarula.com/docs/psa/v0.3/how-to/admin-plugin-surfaces) — The "Connector?" column is ADR 0017 decision 3, and the split is by KIND, not by who wrote the plugin. - [How to write and build a plugin](https://getmarula.com/docs/psa/v0.3/how-to/write-a-plugin) — A plugin is a signed WebAssembly module with no WASI and three exports. This walkthrough takes a handler from an empty crate to an installable bundle. - [How to configure the plugin consent flow](https://getmarula.com/docs/psa/v0.3/how-to/admin-plugin-consent) — Installing a plugin or external connector in an MSP platform is a high-trust security decision. - [How to customize without code](https://getmarula.com/docs/psa/v0.3/how-to/customize) — Every MSP names its ticket columns, client fields, and routing rules a little differently. ## Self-host and operate - [How to upgrade to the latest release](https://getmarula.com/docs/psa/v0.3/how-to/upgrade) — Marula guarantees you can always upgrade from either of the two previous tagged releases (the N−2 rule, policy §1/§3). This guide gets you there safely. - [How to export your data](https://getmarula.com/docs/psa/v0.3/how-to/export-data) — Marula keeps your organization's records in its own database. When you need a copy outside the app, for a migration, a compliance request, or a look at the… - [How to run the local demo stack](https://getmarula.com/docs/psa/v0.3/how-to/local-demo-stack) — Take a fresh clone to a booted, seeded demo with Postgres, Valkey and the sample organization. - [How to change the embedding model](https://getmarula.com/docs/psa/v0.3/how-to/operator-embedding-model) — The embedding model decides what search can match on meaning. It serves the whole install, so a change is a deployment decision, not an organization setting. - [How to choose the retrieval mode](https://getmarula.com/docs/psa/v0.3/how-to/operator-retrieval-mode) — The search vector leg has one exact answer and two indexed shortcuts. Which one fits depends on the shape of the install, and the shapes pull in opposite… - [How to watch your self-hosted services](https://getmarula.com/docs/psa/v0.3/how-to/admin-self-host-services) — The Settings → Self-host services pane answers two operator questions in one place: is the stack running, and where do I look when it is not. ## Reference - [Reference](https://getmarula.com/docs/psa/v0.3/reference) — Reference pages give you exact endpoints, database view columns, environment variables, and operator runbooks for lookup. - [API reference](https://getmarula.com/docs/psa/v0.3/reference/api) — Marula Core API reference: endpoints, operations, request bodies and schemas from the committed OpenAPI pin. - [The OpenAPI pin](https://getmarula.com/docs/psa/v0.3/reference/openapi) — The API contract is pinned twice, and CI enforces that the two are a byte-identical pair: - [Glossary](https://getmarula.com/docs/psa/v0.3/reference/glossary) — The words this documentation assumes. Terms are grouped by where you meet them, not alphabetically, because "what is a board" and "what is an optimistic… - [Billing schema reference](https://getmarula.com/docs/psa/v0.3/reference/billing-schemas) — The tables behind work-type categories, billing verification, contract pricing and project milestone billing, and the rules an integrator has to know before… - [Read model view catalog](https://getmarula.com/docs/psa/v0.3/reference/read-model) — The documented read model is a stable, versioned set of SQL views over operational data — the supported interface for direct SQL access and external… - [Routing and travel reference](https://getmarula.com/docs/psa/v0.3/reference/routing) — System facts about the routing provider seam, its endpoints, its settings, and the reconciliation surface. - [Runbook: backup and restore](https://getmarula.com/docs/psa/v0.3/reference/backup-restore) — Everything in Marula lives in the Postgres database, and once S3 object storage is enabled also the object-storage (Garage/S3) bucket. - [Self-host reference: the local stack](https://getmarula.com/docs/psa/v0.3/reference/self-host-local-stack) — The canonical local stack: Postgres, Redis, schema migration, core API, worker and web console. - [Local AI: transcription and embeddings on your own hardware](https://getmarula.com/docs/psa/v0.3/reference/self-host-local-ai) — Marula's AI features talk to a model runtime you choose. The core ships no model weights, in no image, under no profile. - [Observability: distributed traces, logs, metrics](https://getmarula.com/docs/psa/v0.3/reference/self-host-observability) — Marula's telemetry is off by default. With OTELEXPORTEROTLPENDPOINT unset, core-api and the worker run exactly as they did before the observability work… - [Runbook: reverse proxy and TLS](https://getmarula.com/docs/psa/v0.3/reference/reverse-proxy-tls) — This runbook is the front door. It covers what the proxy must serve, the two TLS modes a real deployment runs, the two ways to run the edge one, the… - [Database observability](https://getmarula.com/docs/psa/v0.3/reference/db-observability) — Marula measures performance one endpoint at a time. That leaves the real query mix unseen and the slow tail unmeasured, so the database now records both. - [Upgrading Postgres 17 to 18](https://getmarula.com/docs/psa/v0.3/reference/pg18-upgrade) — Marula runs Postgres 18 + pgvector everywhere since the 2026-09 transition (deploy/docker-compose.yml, the Helm chart, and the desktop test app all pin… - [Upgrade matrix](https://getmarula.com/docs/psa/v0.3/reference/upgrade-matrix) — Every tagged Marula release and the N−2 upgrade paths proven in CI, with the fixture anchors and covered surfaces. - [Embedding model catalogue](https://getmarula.com/docs/psa/v0.3/reference/embedding-model-catalogue) — Marula turns tickets, comments, clients and knowledge articles into vectors so search can match on meaning as well as words. ## Explanation - [Explanation](https://getmarula.com/docs/psa/v0.3/explanation) — These pages explain why Marula works the way it does: why renaming a board column never breaks an SLA timer, why billing corrections create credit notes… - [Why we're building Marula](https://getmarula.com/docs/psa/v0.3/explanation/why-marula) — Marula's positioning narrative, quoted verbatim: why the PSA was built and what it refuses to repeat. - [Instant-first interaction](https://getmarula.com/docs/psa/v0.3/explanation/instant-first) — When you are on the phone with a customer and updating a ticket's priority or assignee, you shouldn't have to hunt for a Save button at the bottom of a form… - [AI: deny-by-default and the decision harness](https://getmarula.com/docs/psa/v0.3/explanation/ai-deny-by-default) — Marula ships AI deny-by-default: the org switch stays off until grants, caps and credentials make a surface audible. - [Customizations are data, not code](https://getmarula.com/docs/psa/v0.3/explanation/customizations-are-data) — Every MSP runs its service desk a little differently: you have your own board column names, custom client fields, SLA rules, and ticket automations. - [Provenance vs audit: two append-only ledgers, different granularity](https://getmarula.com/docs/psa/v0.3/explanation/provenance-vs-audit) — When an owner or service lead asks "Who changed this client's billing rate?" or "Who viewed that domain admin password yesterday?", you need a straight… - [Billing corrections, and where tax lives](https://getmarula.com/docs/psa/v0.3/explanation/billing-corrections) — An issued invoice is a record of what happened, not a draft that can be tidied up later. - [Contracts: one shape per client relationship](https://getmarula.com/docs/psa/v0.3/explanation/contract-relationship-types) — A Marula contract is the commercial answer to one question: how does this client pay for this work? - [FX additivity and the append-only rate book](https://getmarula.com/docs/psa/v0.3/explanation/fx-additivity) — Two contracts govern money in multi-currency stacks, and they travel together. The command-side procedure is the FX how-to; this page explains the why they… - [Knowledge-base categories and the secret vault share one grant model](https://getmarula.com/docs/psa/v0.3/explanation/kb-class-categories) — Your runbooks in the Knowledge Base (/kb) and your stored credentials in the Secret Vault (/passwords) use the exact same folder permission model (ADR 0006). - [The portal isolation model](https://getmarula.com/docs/psa/v0.3/explanation/portal-isolation) — The portal is not a theme on the staff product. It is a separate trust zone with its own principals, its own sign-in shell, and its own knowledge gate. - [The upgrade compatibility policy](https://getmarula.com/docs/psa/v0.3/explanation/upgrade-policy) — Marula asks organizations to bet their operating system on it. That bet is only rational if upgrades are boring. Two commitments define the whole document: ## Troubleshooting - [Troubleshooting](https://getmarula.com/docs/psa/v0.3/troubleshooting) — Start from what you see. Each entry below names a symptom in plain words, the checks in the order they usually find it, and the page that explains the part… ## Get help - [How to get help inside Marula](https://getmarula.com/docs/psa/v0.3/how-to/get-help) — Every entry is a page from the public docs site — the same markdown that lives at getmarula.com/docs.