Core concepts
The seven words the rest of the documentation assumes you know — and how Dibbla's main surfaces fit together.
Deliberately short. These are the words the rest of the documentation leans on; everything else is explained where it is used.
The two main surfaces
Most confusion between colleagues comes from not having these apart:
| The console | The portal | |
|---|---|---|
| Who uses it | you, building and operating | your organisation, using what you built |
| What it shows | deploys, logs, secrets, databases, version history | a catalogue of the apps you may open |
| Where | console.dibbla.com | app.dibbla.com |
Sending a colleague a console link when they wanted the app is the single most common mix-up on this platform.
Both sidebars name the surface you are in — Portal or Console. Select that name to open the surface switcher and move to another available Dibbla surface in the same tab. Your sign-in and selected organisation carry across; destinations that are not configured for your Dibbla installation are left out.
If you only use an app and follow a direct console link, the console hands you back to the useful place instead of showing an access error: My Apps when an app has been shared with you, otherwise Support. You can still choose Continue to console, and a deep link keeps its original destination. The handoff is guidance between peer surfaces, not a permission wall.
The seven words
App — one deployed thing, identified by its alias (lumen). The alias
is the name you pass to every command; the hostname it is served on is that
alias plus a short suffix for your organisation.
Deployment — one shipped version of an app. Every deploy is also a commit
in a repository the platform keeps for you, with your -m message as its
subject, so an app has a history whether or not you kept one.
Organisation — the boundary everything lives inside. Databases, secrets and apps belong to an org, not to a person. Being in an org is what lets a colleague see all of its apps in the portal. It is not the only way in: an app that requires login can be set to invite only, and then you invite a person to that one app by e-mail — they get the app in their portal, under the name of your organisation, without joining it. The portal lists what a person may open, wherever it lives: their own org’s apps first, apps shared from other orgs under Shared with you, and for someone who belongs to no org, only what they were given.
Secret — a value your app receives as an environment variable, and that Dibbla hands to nothing else: no Dibbla API, CLI command or MCP tool returns it. It gets in from a person — typed in their own terminal or on a Dibbla page — or the platform creates it, like a database’s connection string. A plain env var is the opposite — a setting anyone who can read the app’s configuration can read. Secrets are global to the org or scoped to one app or one service. More in Env vars and secrets.
Database — managed Postgres, owned by the org rather than by an app. Creating one also creates the secret that carries its connection string.
Workflow — a graph of function calls the platform runs for you, with an HTTP endpoint of its own. Useful once a job outgrows a request handler; not something you need on day one.
Handbook — the markdown under docs/ in your project, rendered for your
users in the portal. Its subtitle is the line colleagues read in the
catalogue.
Function — an implementation a workflow node can call.
Tool server — a process that registers functions with the workflow engine and runs them on demand. It is a gRPC client: it dials out to the engine and holds one stream, so it needs no open port and no deploy — which is why you can run one from your own laptop and have a workflow call into it. A worker you write with the Go SDK is a tool server — the one you run yourself; the platform ships its own built-in one too. (You will see the older label “Pipeline Host” in a couple of places; it means this.)
Both are explained in the Workflows chapter, which is deliberately late.
What the platform gives every app, unasked
Worth knowing early, because it shapes what you don’t have to build:
- a URL, with TLS
- an optional login gate and access policy, enforced before your code runs —
and, once you turn it on, the signed-in user’s identity passed to your app
as
X-User-*headers - logs, without cluster access
- an LLM gateway your app can call with its Dibbla token instead of a provider key
- a place for the review that shipped with the deploy
- a way for your app’s users to reach you — support tickets, switched on per app, with the thread hosted for you
The tour is a walk through those, one at a time.