Keelson SDK

The Keelson SDK provides libraries for using file storage, user information, background tasks, and other Keelson features from your app’s code. It is available for Python, Node.js (JavaScript / TypeScript), and Go. Use only the features you need.

You do not need the SDK just to deploy an app. Add it when you want to keep uploaded images, for example, or tailor the app to the signed-in user. When asking an AI agent to implement a feature, tell it your app’s language and what you want to achieve, and share this page or the relevant guide.

Available features

Feature	What it does	Guide
Files SDK	Save, read, update, delete, and list private files used inside the app, such as configuration JSON or records of processed data	Files and media: Files
Media SDK	Store images, PDFs, and attachments, and serve them by URL to members who can view the app. Use it for product photos or application forms	Files and media: Media
Identity SDK	Read the signed-in user’s information, group memberships, and workspace member information. Use it to record authors or vary behavior by group	Use signed-in user information
Tasks SDK	Enqueue a command declared under tasks in keelson.yaml to run on a separate instance, and check its status. Use it for work that continues after a request, such as generating PDFs or heavy external API calls	Background tasks

Use Database (Managed SQLite) for customer records, projects, and other data that needs querying or concurrent updates. Connect with a libSQL client for your language, installed separately from the Keelson SDK.

Installation

Add dependencies for your app’s language. The core features are shared across all three languages, but function names, arguments, and helper features vary.

Python

All features are bundled in keelson-sdk.

pip install keelson-sdk

Import the feature you need, for example from keelson import files. Available modules are files, media, identity, and tasks. Record the dependency in requirements.txt or pyproject.toml, according to your dependency manager.

Node.js (JavaScript / TypeScript)

Each feature has its own package. Install only those you need.

Feature	Install
Files	npm install @keelsonhq/files
Media	npm install @keelsonhq/media
Identity	npm install @keelsonhq/identity
Tasks	npm install @keelsonhq/tasks

Import a package with, for example, import * as files from "@keelsonhq/files".

Go

One module contains packages for each feature.

go get github.com/keelsonhq/go-sdk

Import the package you need, such as github.com/keelsonhq/go-sdk/files. The module includes files, media, identity, and tasks; use directory to list members and groups.

Use the SDK on Keelson

Use the SDK in server-side code, not in JavaScript running in the browser. Static sites and SPAs have no server, so they cannot use the SDK. To use these features, add an API server that calls the SDK and deploy as a hybrid app.

Keelson provides connection details and credentials through environment variables for each feature. The SDK normally reads them automatically, so you do not need to put tokens or storage locations in your code.

• Files / Media: No additional keelson.yaml configuration is needed.
• Identity: No setup is needed to read basic user information from headers. To retrieve groups or member information, enable the Directory API and redeploy.
• Tasks: Declare the tasks you enqueue under tasks in keelson.yaml and deploy. See Background tasks.

Local development

Without Keelson connection settings, Files and Media save to local folders. Identity can return test user information with KEELSON_LOCAL_MODE=1. Tasks runs the command synchronously on your machine through the CLI’s keelson dev task run (see Run locally). Local files and test user information are not automatically carried over to your deployed app.

Files has language- and OS-related considerations. See Files and media: local development for storage locations and constraints, and Identity: local development for testing user information. The environment variables reference lists settings used by the SDK.