Self-hosting overview
When to run your module, app or service outside Maru, what you take on when you do, and how it differs from building on Maru's hosted platform.
Most modules don't need this section. When your module runs on Maru (in Studio, on its module page or at its
maru.pageaddress), sign-in, consent, saved presets and generation credits are handled for you. There is no server, token or callback to run. Start on the Free plan, which is free forever, and add sign-in with one account button.
Self-hosting means your code runs somewhere Maru does not: your own website or web app, your own backend, a native app you distribute yourself, or a service that calls Maru on people's behalf. Everything you build with Maru stays yours and can run there. This section covers what changes when it does.
Maru-hosted or self-hosted
| On Maru | Self-hosted | |
|---|---|---|
| Where it runs | Studio, the module page, <name>.maru.page | Your site, server, app or plug-in |
| Sign-in | The host's account button. You write no auth code | Your app runs OAuth with PKCE and stores the session |
| Consent and permissions | Maru's consent page, opened by the host | The same consent page, reached from your redirect |
| Presets and saved state | face.appAuth saves to the person's account | Your app calls the presets API with its session |
| Generation | face.appGeneration, billed to each person's own credits | Your server holds a token, or your app uses the person's session |
| Secrets | None | You keep tokens and any client secret out of browsers and bundles |
| Callbacks and hosting | Derived from your module's address | You register and serve exact HTTPS callbacks |
| Updates | maru publish | Your own deployment |
The capabilities match on both sides, but self-hosting moves the plumbing to you.
When self-hosting makes sense
- Your product already has its own website, accounts or backend, and Maru is one feature inside it.
- You run a service that generates or analyzes audio for your own users, under your own terms and billing.
- You distribute a native app or plug-in outside Maru and want it to sign in with a Maru account.
- You need data to stay on infrastructure you control.
If none of these apply, build on Maru and come back when one does. You can move a module between the two later: the face and Processor code are the same, and only the host around them changes.
What you take on
- An app registration. Create one in Creator apps with your exact callback addresses and the permissions you need.
- Sign-in. Run the PKCE flow, keep the session and handle sign-out and account switching. See Maru sign-in in your own app.
- Credentials. A personal token or client secret lives only on your server. A browser, a face and a plug-in hold only the public app id.
- Generation and cost. Jobs submitted with your token are billed to your account. Jobs submitted with a person's session use their credits after they approve. See Generation from your own server.
- Operations. Retries, request keys, storage of results, monitoring and the experience when Maru is unreachable.
Pages in this section
- Maru sign-in in your own app: register an app, run PKCE sign-in, verify identity on your backend.
- Generation from your own server: submit jobs with a token, or with a signed-in person's session.
- Build and publish a module in CI: build releases on your own runner.
- Check a license from your own server.