Getting started

What Sarpius is

A Project is one application. It is made of one or more deployable Components (for example a Svelte front-end, a PHP or Java back-end, and worker services) plus the infrastructure they share: routing, databases, and storage buckets. Your code can live in a single repository (a monorepo) or several; the platform figures out the shape.

The Project is the primary place you work. Deploy, environment variables, databases, storage, routing, members, activity, and usage all live inside the Project workspace, so you do not leave the platform to glue separate tools together. The standalone engines underneath (Sarpius Launch for provisioning, Sarpius Router for routing and TLS, Sarpius DB for managed databases, Sarpius Store for object storage) are still there under an Advanced surface for power users, but you rarely need to touch them directly.

• Connect a git source and the platform detects Components, frameworks, routes, and the databases or buckets each needs.
• Push to your default branch and the build and deploy happen automatically.
• Your app is served on a generated subdomain, or on a custom domain with automatic TLS.
• Container time is billed per minute from your wallet, so you only pay while things run.

Before you start

You need one thing to deploy: a Sarpius account. The first app on your account runs on the free tier, which is not metered and is never suspended for an empty wallet, so you can push your first deploy before you have paid us anything. Fund your wallet before you grow past it: a second app, a custom domain, bandwidth beyond the included allowance and managed databases are all billed per minute against your balance, and those are the resources that stop when it runs out.

If you plan to connect a private repository, connect your git account (or add a personal access token, or an SSH key) in your profile first. The wizard reads private repositories with your connected git account, so it never asks you to paste a token inline. Public repositories need no credentials at all.

Quickstart: connect a repo and deploy

The fastest path to a live app is to connect an existing repository and let the platform do the rest. From your Projects list, choose to create a new Project, then pick the connect-a-git-repo path.

1. Give the Project a name. It is prefilled from the repository name, so you can usually leave it as is.
2. Paste one repository URL. That is all that is required: no provider, no branch, and no token field. You can add more repository rows if your app spans several repos.
3. Select Detect. The platform scans the repository and resolves a blueprint: the Components it contains, the databases or buckets they need, and the branch it actually scanned.
4. Review the reveal. Your Project appears as one app frame with each detected Component as a row, plus any detected databases, Redis, or storage buckets, a routing table, and a domain choice.
5. Select Deploy. The platform provisions the Components and their shared infrastructure and lands you in the new Project workspace, where you can watch the build and deploy progress.

When the deploy finishes, your app is reachable on its generated subdomain. The Project workspace is now your home for everything that follows: redeploys, environment variables, databases, routing, and members.

Other ways to start a Project

Connecting an existing repository is one of three starting points offered when you create a Project. If you do not have a repository yet, the other two scaffold a fresh one for you.

• Optimized Full Stack (recommended): name your Project and the platform scaffolds a preset, a Svelte front-end served at "/", a FRMWRK back-end served at "/api", and a managed Postgres database wired to the back-end automatically. Nothing else to configure.
• Custom Full Stack: choose your own Components and frameworks in a small builder (for example front-end at "/" and back-end at "/api"), still auto-wired and provisioned for you.
• Connect a git repository: bring an existing app; the platform detects its Components and infrastructure (the Quickstart above).

The Optimized and Custom paths create the git repositories for you and seed them, then deploy, so you land in a working Project with code you own and can edit from day one.

How detection and the reveal work

Detection is magic-first: you provide the least possible input and the platform resolves the rest server-side. When you select Detect, the wizard asks the backend for a blueprint of each repository and merges the results into a single plan.

• Components: each detected app becomes a Component row, with its framework, runtime, and the route it serves. Worker Components do not serve HTTP and get no route.
• Databases and storage: a detected need for Postgres, Redis, or a storage bucket becomes a shared service, attached to the Components that use it. The same database declared by Components in different repos becomes one shared service.
• Routing: a routing table maps paths to Components. There is always exactly one catch-all "/" rule, and other Components can mount at their own prefix such as "/api". By default a non-root prefix is stripped before the request reaches the Component, since most back-end frameworks do not want the prefix baked into their own routes.
• Domain: by default your Project gets a free, automatically generated subdomain on sarpius.app (an adjective, a noun, and a short unique tail; the name is generated, not chosen). You can instead enter a custom domain here.

The reveal is editable. Select Add another repo to detect a second repository and merge its Components into the same app. Select Adjust the plan to open the power-user editor, where you can rename, add, or remove Components and services, with a live system map of the result. When you are happy, one Deploy button provisions everything.

Push to deploy

After the first deploy, Sarpius keeps your app in sync with your repository. A webhook is installed on the connected repository, so pushing to the deployed branch triggers a fresh build and deploy with no manual step.

1. Commit and push a change to your default (deployed) branch.
2. The build runs in a sandboxed builder, then the new version rolls out.
3. Follow progress in the Project workspace deploy log; the live URL stays the same across redeploys.

Add a custom domain

Your generated subdomain works immediately, but you will usually want your own domain in front of the app. You can set a custom domain during the reveal, or add one later from the Project workspace routing surface.

1. Add the custom domain to your Project and note the target it should point at.
2. Create the DNS record for your domain at your DNS provider so it resolves to the platform edge.
3. Wait for the platform to verify the record. Sarpius Router then issues a TLS certificate for the host over ACME and serves your app over HTTPS.
4. Certificates renew automatically, so there is nothing to rotate by hand.

Limits and notes

• The integrated Project workspace ships incrementally. Deploy and routing with TLS work end to end today; the in-browser editor (Sarpius Code) is arriving this quarter. You can still edit code in your own repository and push to deploy in the meantime.
• A Project is always exportable. Owning your whole app is only acceptable if you can walk out with it, so export is a first-class capability, not an afterthought.
• Container time is billed per minute against your wallet. Static Components can be served from storage rather than a running container, so they are billed on storage only.
• A blank Project can be created and provision its row while individual Components fail (for example a pending database migration). If nothing came up, the wizard tells you why rather than dropping you into an empty Project.