Core concepts

Keelson keeps your internal apps and members together in a workspace. You do not need to rebuild login or member management every time you add an app.

This page introduces the key terms and explains which features Keelson provides and which your app implements.

Key terms

Term	Meaning
Workspace	A place to manage members and apps together
App	A business tool you deploy and use, such as a sales tracker or daily report app
Member	A person who belongs to a workspace
Group	A collection of members, such as a department or team, that you can assign access to together
Deploy	Send your app’s code and configuration to Keelson so it can run there

For example, you could create a sales report app and an expense request app in the same workspace, then share the sales report with the sales team and the expense app with all employees.

What happens when someone opens an app

Deploying a web app or static site gives it a dedicated HTTPS URL. Keelson obtains and renews the certificate.

https://<workspace>--<app>.keelson.run

Knowing the URL is not enough to open a regular app page. Keelson checks that the visitor is signed in and has permission to view the app, then passes authorized requests to it.

Browser
   ↓
Keelson: checks login, app access, and IP restrictions
   ↓
App: displays pages and runs business logic

Your app does not need to implement a login page or manage Keelson login sessions. It can identify the visitor using the user information Keelson supplies.

Requests that do not use browser login, such as webhooks from external services, need separate configuration. See External integrations.

Manage members and access in one place

After signing in once, a user can open any app they have access to in the same workspace. They do not need to sign in to Keelson separately for each app. If an app also uses its own external authentication, that service may require a separate login.

Assign app permissions to groups

You manage members and groups in the workspace, then assign permissions to groups for each app.

Permission	What it allows
View (`view`)	Open and use the app
Manage (`manage`)	Deploy the app and change its settings and secrets

View permission lets someone access and use an app. Whether they can create or edit data inside it depends on the app’s code.

New apps start with these permissions:

Group	Members	App permission
`everyone`	All workspace members	View
`developers`	Members with the Owner, Admin, or Developer role	Manage, which includes view

To restrict an app to a specific team, see Share an app with your team.

App management permission is separate from business approval authority. Rules such as “only a manager can approve a request” or “only the assigned person can edit a case” belong in your app, using user and group information.

What Keelson provides and what your app implements

For storage, you can use Managed SQLite, a dedicated database managed by Keelson, and the Files / Media SDK, libraries for storing and retrieving files, images, and videos. Responsibilities are divided as follows:

Feature	Keelson provides	Your app implements
Pages and business logic	An app URL and runtime environment	Forms, reports, approval requests, and other features
Login and permissions	Login, member management, and checks on who can open an app	Business rules, such as showing only the current user’s data
Data storage	Managed SQLite and the Files / Media SDK	Code that connects to storage and reads and writes data
API keys and other secrets	Storage and delivery of secrets to the app	Code that uses the supplied keys to connect to external services
Scheduled jobs	Starting work at configured times or intervals	Code that performs one run of the task and exits
Operations	Logs, app listings, and Managed SQLite backup and restore	Logging business outcomes and errors

You can describe the features you want to an AI agent and ask it to create the app code and Keelson configuration.

Shared features you can use

Manage API keys as secrets

Set shared API keys at the workspace level and pass them to apps as environment variables. An app can override a shared value with its own. You do not need to put secret values in source code or keelson.yaml.

See Environment variables and secrets.

Give your app its own database

Add this to keelson.yaml to provision a dedicated Managed SQLite database:

db:
  mode: libsql

Keelson supplies the connection information. Your app implements the code to connect and read or write data.

Managed SQLite includes backup and restore. Files / Media files are not included in those backups. See Databases and Files and media to choose the right storage.

Run tasks at set times or intervals

Configure daily reports or recurring data synchronization under crons in keelson.yaml. Jobs can run even when no one is visiting the web app. See Scheduled jobs.

Check app activity from the app list

The console shows who created each app, who can use it, and when it was last used or deployed. Other members can understand how an app is managed without relying on its creator.

What to know about startup and storage

Web apps stop after a period without requests. They start again on the next request, so the first response after stopping may take longer. Work that continues after a response has been sent is not guaranteed to finish.
Files on the app server are temporary. They can be lost on restart or redeployment. Store data you need to keep in Managed SQLite or through the Files / Media SDK.

See When apps run and Supported apps and constraints for implementation details.