#Native SDK: Data and System
The Native SDK for files, SQLite, key-value storage, secrets, networking and the permissions that gate them, from Go and from TypeScript with @krate/app.
Experimental. Part of Krate Native, which is under construction. Ids and permission names are fixed; more may be added.
The SDK is a set of Go packages under packages/native/sdk. Go host code
imports them and calls plain functions. The UI and TypeScript host code reach
selected operations through host ids named krate/<area>.<name>, wrapped by
@krate/app/os, @krate/app/fs, @krate/app/db, @krate/app/kv and
@krate/app/permission. The shell registers the SDK for every app. The
windows, dialogs, clipboard, menus, tray, shortcuts, notifications and
lifecycle have their own page; they share the
permission list, the denial error and the id table below.
import { appDataDir, info } from "@krate/app/os";
import * as kv from "@krate/app/kv";
import * as db from "@krate/app/db";
await kv.set("theme", "dark");
await db.exec("CREATE TABLE IF NOT EXISTS notes(id INTEGER PRIMARY KEY, body TEXT)");
const { lastInsertId } = await db.exec("INSERT INTO notes(body) VALUES(?)", "hello");
const rows = await db.query<{ id: number; body: string }>("SELECT * FROM notes");
console.log(await appDataDir(), (await info()).os);#Permissions
(Native plugins define their own permissions, plugin:<plugin>.<permission>; see
Native plugins.)
app.json has a permissions list. Go and TypeScript host code are trusted and
never checked (a TypeScript call through __krateHost.call reaches the ungated
implementation); permissions decide which ids the UI may call.
| Permission | Default | Grants |
|---|---|---|
os:info |
yes | App directories and OS information |
kv |
yes | The key-value store |
db |
yes | The SQLite database |
fs |
no | Writing files inside the allowed folders; implies fs:read |
fs:read |
no | Reading files inside the allowed folders |
os:secrets |
no | Setting and deleting secrets |
os:secrets.read |
no | Reading secrets; os:secrets does not imply it |
shell:openExternal |
no | Opening http, https and mailto URLs in the default handler |
net |
no | Reserved for a network policy; no UI id uses it yet |
window |
yes | Opening and controlling windows |
app |
yes | Quitting, relaunching, capability checks, second-instance events |
menu |
yes | The application menu and context menus |
dialog |
yes | Native file and message dialogs |
notify |
yes | Desktop notifications |
clipboard |
yes | Writing the clipboard |
clipboard:read |
no | Reading the clipboard (sees what the user copied elsewhere) |
tray |
no | A system tray icon |
shortcut |
no | Global keyboard shortcuts |
share |
no | The system share menu for text, URLs and files |
updater |
no | Checking for, downloading and applying app updates, and relaunching; see Updates |
page |
no | Print, find in page, zoom and capture the app's own views; see Web contents |
downloads |
no | Choosing where page downloads go, watching and cancelling them; see Web contents |
cookies |
no | Reading, writing and deleting cookies, clearing site data and the cache; see Web contents |
remote |
no | Views and windows with web pages that have no access to the app, navigating them and the message channel; see Remote content |
remote:intercept |
no | Block, redirect and add headers to the requests of remote views, and watch them |
remote:network |
no | User agent and proxy of remote partitions, certificate decisions, logins, client certificates and clearing remote data |
An empty or missing list means the defaults: the non-sensitive set marked
"yes" above. krate native build writes the list for you: it
derives the permissions from the
@krate/app/<area> imports and krate/<area>.<op> ids the UI and TypeScript
host code use, and native.permissions in the config is an allowlist that fails
the build (KR7210) when the code needs something it does not list. A
non-empty list grants exactly what it names (plus what a name implies), so an
app that lists only fs loses kv and db unless it lists them too. Unknown
names are an error when the app loads. Permissions are read once at start;
changing them needs a restart.
A call to an id whose permission is missing rejects with a KrateError:
{ "code": "permission_denied", "message": "...", "data": { "permission": "os:secrets.read" } }This holds for every id, data and UI alike (krate/window.open without
window is a permission_denied, not a not_found). An id that does not exist at all is not_found, so the UI can tell a missing
permission from a typo. isPermissionDenied(e) and deniedPermission(e) from
@krate/app/permission read this, and query(name) (host id
krate/permission.query, always allowed) asks whether a permission is granted.
#Ids
All ids are krate/<area>.<operation> with a lowerCamel operation name
(krate/os.info, krate/kv.get, krate/window.open). Your own Go functions keep
their Go names (src/lib/tasks.List).
| Id | Permission | Arguments | Result |
|---|---|---|---|
krate/os.appDataDir |
os:info |
none | string |
krate/os.cacheDir |
os:info |
none | string |
krate/os.configDir |
os:info |
none | string |
krate/os.logDir |
os:info |
none | string |
krate/os.tempDir |
os:info |
none | string |
krate/os.info |
os:info |
none | OsInfo |
krate/os.openExternal |
shell:openExternal |
url |
nothing |
krate/os.secretSet |
os:secrets |
key, value |
nothing |
krate/os.secretGet |
os:secrets.read |
key |
string or null |
krate/os.secretDelete |
os:secrets |
key |
nothing |
krate/fs.readFile |
fs:read |
path |
Uint8Array |
krate/fs.readText |
fs:read |
path |
string |
krate/fs.readDir |
fs:read |
path |
DirEntry[] |
krate/fs.stat |
fs:read |
path |
FileInfo |
krate/fs.exists |
fs:read |
path |
boolean |
krate/fs.writeFile |
fs |
path, data |
nothing |
krate/fs.writeText |
fs |
path, text |
nothing |
krate/fs.mkdir |
fs |
path |
nothing |
krate/fs.remove |
fs |
path, recursive? |
nothing |
krate/fs.rename |
fs |
from, to |
nothing |
krate/db.exec |
db |
sql, params? |
{ rowsAffected, lastInsertId } |
krate/db.query |
db |
sql, params? |
array of row objects |
krate/db.transaction |
db |
statements |
array of exec results |
krate/kv.get |
kv |
key |
value or null |
krate/kv.set |
kv |
key, value |
nothing |
krate/kv.delete |
kv |
key |
nothing |
krate/kv.keys |
kv |
prefix? |
string[] |
krate/updater.check |
updater |
none | { version, notes, pubDate, size, critical, required, delta, downloadSize } or null |
krate/updater.download |
updater |
none (stream) | { done, total } progress events |
krate/updater.apply |
updater |
none | nothing |
krate/updater.relaunch |
updater |
none | nothing |
krate/updater.markHealthy |
updater |
none | nothing |
krate/updater.status |
updater |
none | { version, channel, unconfirmed, rollback } |
krate/updater.ackRollback |
updater |
none | nothing |
krate/updater.setChannel |
updater |
channel: string | nothing |
krate/permission.query |
none | name |
boolean |
krate/window.open |
window |
options: WindowOptions |
string |
krate/window.list |
window |
none | string[] |
krate/window.state |
window |
window: string |
WindowState |
krate/window.close |
window |
window: string |
nothing |
krate/window.setTitle |
window |
window: string, title: string |
nothing |
krate/window.setSize |
window |
window: string, width: number, height: number |
nothing |
krate/window.setPosition |
window |
window: string, x: number, y: number |
nothing |
krate/window.setAlwaysOnTop |
window |
window: string, on: boolean |
nothing |
krate/window.setFullscreen |
window |
window: string, on: boolean |
nothing |
krate/window.setFrameless |
window |
window: string, on: boolean |
nothing |
krate/window.minimize |
window |
window: string |
nothing |
krate/window.maximize |
window |
window: string |
nothing |
krate/window.restore |
window |
window: string |
nothing |
krate/window.focus |
window |
window: string |
nothing |
krate/window.show |
window |
window: string |
nothing |
krate/window.hide |
window |
window: string |
nothing |
krate/window.setPreventClose |
window |
window: string, on: boolean |
nothing |
krate/window.navigate |
window |
window: string, path: string |
nothing |
krate/window.events |
window |
none (stream) | WindowEvent |
krate/window.fileDrops |
window |
none (stream) | FileDropEvent |
krate/window.thisView |
window |
none | string |
krate/chrome.state |
window |
window: string |
ChromeState |
krate/chrome.setTitleBar |
window |
`window: string, style: "native" | "hidden" |
krate/chrome.setBackdrop |
window |
window: string, name: Backdrop |
nothing |
krate/chrome.setVibrancy |
window |
`window: string, material: Vibrancy | ""` |
krate/chrome.setTitleBarOverlay |
window |
`window: string, overlay: TitleBarOverlay | null` |
krate/chrome.setTrafficLightPosition |
window |
window: string, x: number, y: number |
nothing |
krate/chrome.startDrag |
window |
window: string |
nothing |
krate/chrome.toggleMaximize |
window |
window: string |
nothing |
krate/chrome.setDocumentEdited |
window |
window: string, on: boolean |
nothing |
krate/chrome.setRepresentedFile |
window |
window: string, path: string |
nothing |
krate/chrome.attachSheet |
window |
window: string, child: string |
nothing |
krate/chrome.endSheet |
window |
window: string |
nothing |
krate/chrome.setTabbing |
window |
window: string, identifier: string, mode: TabbingMode |
nothing |
krate/chrome.mergeAllWindows |
window |
window: string |
nothing |
krate/chrome.moveTabToNewWindow |
window |
window: string |
nothing |
krate/chrome.tabs |
window |
window: string |
string[] |
krate/chrome.setThumbButtons |
window |
window: string, buttons: ThumbButton[] |
nothing |
krate/chrome.share |
share |
window: string, items: ShareItems |
nothing |
krate/chrome.setJumpList |
app |
tasks: JumpTask[] |
nothing |
krate/chrome.clearJumpList |
app |
none | nothing |
krate/chrome.setActivationPolicy |
app |
`policy: "regular" | "accessory" |
krate/chrome.setDockVisible |
app |
on: boolean |
nothing |
krate/chrome.events |
window |
none (stream) | ChromeEvent |
krate/dialog.openFile |
dialog |
options: OpenOptions |
string[] |
krate/dialog.openFolder |
dialog |
options: OpenOptions |
string[] |
krate/dialog.saveFile |
dialog |
options: SaveOptions |
`string |
krate/dialog.message |
dialog |
options: MessageOptions |
number |
krate/clipboard.writeText |
clipboard |
text: string |
nothing |
krate/clipboard.writeImage |
clipboard |
png: Uint8Array |
nothing |
krate/clipboard.writeFiles |
clipboard |
paths: string[] |
nothing |
krate/clipboard.clear |
clipboard |
none | nothing |
krate/clipboard.readText |
clipboard:read |
none | string |
krate/clipboard.readImage |
clipboard:read |
none | `Uint8Array |
krate/clipboard.readFiles |
clipboard:read |
none | string[] |
krate/clipboard.write |
clipboard |
data: ClipboardData |
nothing |
krate/clipboard.writeFormat |
clipboard |
name: string, data: Uint8Array |
nothing |
krate/clipboard.readHtml |
clipboard:read |
none | string |
krate/clipboard.readRtf |
clipboard:read |
none | string |
krate/clipboard.formats |
clipboard:read |
none | string[] |
krate/clipboard.readFormat |
clipboard:read |
name: string |
`Uint8Array |
krate/menu.setApp |
menu |
items: MenuItem[] |
nothing |
krate/menu.popup |
menu |
window: string, x: number, y: number, items: MenuItem[] |
nothing |
krate/menu.events |
menu |
none (stream) | MenuEvent |
krate/menu.setContextMenu |
menu |
window: string, view: string, options: ContextMenuOptions |
nothing |
krate/menu.contextEvents |
menu |
none (stream) | ContextMenuEvent |
krate/tray.set |
tray |
options: TrayOptions |
nothing |
krate/tray.remove |
tray |
none | nothing |
krate/tray.events |
tray |
none (stream) | TrayEvent |
krate/shortcut.register |
shortcut |
handle: string, accelerator: string |
nothing |
krate/shortcut.unregister |
shortcut |
handle: string |
nothing |
krate/shortcut.events |
shortcut |
none (stream) | {id: string} |
krate/notify.send |
notify |
notification: Notification |
nothing |
krate/notify.close |
notify |
id: string |
nothing |
krate/notify.events |
notify |
none (stream) | NotificationEvent |
krate/app.quit |
app |
none | nothing |
krate/app.relaunch |
app |
none | nothing |
krate/app.supports |
app |
capability: string |
boolean |
krate/app.events |
app |
none (stream) | SecondInstance |
krate/app.openedFiles |
app |
none | string[] |
krate/app.openFileEvents |
app |
none (stream) | OpenFileEvent |
krate/page.print |
page |
view?: string |
nothing |
krate/page.printToPdf |
page |
view: string, options?: PdfOptions |
Uint8Array |
krate/page.find |
page |
view: string, text: string, options?: FindOptions |
nothing |
krate/page.stopFind |
page |
view: string |
nothing |
krate/page.findEvents |
page |
none (stream) | FindEvent |
krate/page.zoom |
page |
view: string |
number |
krate/page.setZoom |
page |
view: string, factor: number |
nothing |
krate/page.capture |
page |
view: string |
Uint8Array |
krate/downloads.configure |
downloads |
options: DownloadOptions |
nothing |
krate/downloads.list |
downloads |
none | DownloadInfo[] |
krate/downloads.cancel |
downloads |
id: number |
nothing |
krate/downloads.events |
downloads |
none (stream) | DownloadEvent |
krate/cookies.list |
cookies |
url?: string |
Cookie[] |
krate/cookies.get |
cookies |
name: string, url?: string |
`Cookie |
krate/cookies.set |
cookies |
cookie: CookieInput, url?: string |
nothing |
krate/cookies.delete |
cookies |
name: string, url?: string |
nothing |
krate/cookies.clearSiteData |
cookies |
options?: ClearOptions |
nothing |
krate/remote.open |
remote |
options: RemoteWindowOptions |
window id |
krate/remote.addView |
remote |
window: string, options: RemoteViewOptions |
view id |
krate/remote.navigate |
remote |
view: string, url: string |
nothing |
krate/remote.post |
remote |
view: string, targetOrigin: string, data: unknown |
nothing |
krate/remote.messages |
remote |
stream | RemoteMessage |
krate/remote.events |
remote |
stream | RemoteEvent |
krate/remote.capabilities |
remote |
none | RemoteCapabilities |
krate/remote.setRules |
remote:intercept |
partition: string, rules: RemoteRule[] |
nothing |
krate/remote.requests |
remote:intercept |
stream | RemoteRequest |
krate/remote.setUserAgent |
remote:network |
partition: string, userAgent: string |
nothing |
krate/remote.setProxy |
remote:network |
partition: string, proxy: RemoteProxy |
nothing |
krate/remote.setClientCertificate |
remote:network |
partition, host, certFile, keyFile: string |
nothing |
krate/remote.clearData |
remote:network |
partition: string, options?: RemoteClearOptions |
nothing |
krate/remote.certificates |
remote:network |
stream | RemoteCertificateError |
krate/remote.answerCertificate |
remote:network |
id: number, allow: boolean |
nothing |
krate/remote.auth |
remote:network |
stream | RemoteAuthChallenge |
krate/remote.answerAuth |
remote:network |
id: number, user: string, password: string, ok: boolean |
nothing |
packages/native/sdk/ids.go is the source of truth for this table; a Go test
checks it against the registrations, the TypeScript wrappers and this page.
#os
Go: package sdkos (packages/native/sdk/os).
dir, err := sdkos.AppDataDir() // also CacheDir, ConfigDir, LogDir, TempDir
info := sdkos.GetInfo() // OS, Arch, OSVersion, Hostname, Locale, AppID, AppVersion
err = sdkos.OpenExternal(ctx, "https://example.com")
err = sdkos.SecretSet(ctx, "api-token", token)
v, err := sdkos.SecretGet(ctx, "api-token") // sdkos.ErrSecretNotFound when missingEach directory is named after the appId and created on first use with mode
0700:
| Directory | Linux | macOS | Windows |
|---|---|---|---|
| App data | $XDG_DATA_HOME/<id> (~/.local/share) |
~/Library/Application Support/<id> |
%APPDATA%\<id> |
| Cache | $XDG_CACHE_HOME/<id> (~/.cache) |
~/Library/Caches/<id> |
%LOCALAPPDATA%\<id>\Cache |
| Config | $XDG_CONFIG_HOME/<id> (~/.config) |
~/Library/Application Support/<id>/config |
%APPDATA%\<id>\Config |
| Log | $XDG_STATE_HOME/<id>/log (~/.local/state) |
~/Library/Logs/<id> |
%LOCALAPPDATA%\<id>\Logs |
| Temp | $XDG_RUNTIME_DIR/<id>, else <tmp>/<id>-<uid> |
<tmp>/<id> |
<tmp>\<id> |
A Go host child process learns the app from KRATE_APP_ID, KRATE_APP_NAME
and KRATE_APP_VERSION, which the shell sets; a Go host that is not started by
the shell calls sdkos.Configure.
OpenExternal accepts only http, https (with a host) and mailto URLs;
sdkos.AllowScheme adds more. It starts xdg-open, open or
rundll32 url.dll,FileProtocolHandler and returns once the handler has started.
#Secrets
Secrets are stored in the OS credential store, scoped to the app id and the key:
| Platform | Store |
|---|---|
| Linux | A Secret Service provider (gnome-keyring, KWallet, KeePassXC) over the session D-Bus, with a built-in pure Go D-Bus client. A locked keyring asks the user to unlock it. |
| macOS | The login Keychain, generic passwords, through Security.framework. |
| Windows | The Credential Manager, generic credentials named <appId>/<key>; a value holds at most 2560 bytes. |
Where there is no store (a Linux machine without a Secret Service provider or a
session bus), the calls fail with krate.ErrUnsupported in Go and code
unsupported in the UI. Check first with krate.Supports("os.secrets").
Capabilities registered by the SDK: os.info, os.openExternal,
os.secrets, fs, db, kv, net.
#fs
Go: package fs (packages/native/sdk/fs). These functions are for paths that
come from the UI; Go host code uses the standard library directly.
A path may be absolute, or relative to the app data directory. It is cleaned, resolved through symlinks and must then lie inside an allowed root:
- the app directories (data, cache, config, log, temp), and
- paths granted at run time with
fs.Grant(path). The dialog SDK calls it when the user picks a file or folder. A granted folder covers its subtree; a granted file covers just that file.
Anything else fails with code permission_denied and data
{ "permission": "fs", "reason": "outside_scope", "path": "..." }, including
.. traversal and symlinks that point outside. exists on such a path fails
too, rather than answering. remove and rename act on a symlink itself, never
its target, and an allowed root cannot be removed or moved. Reads are limited to
64 MiB. The check and the use are not atomic, so the scope protects against a
buggy or hostile page, not a hostile local process.
Other error codes: not_found, already_exists, access_denied (the OS said
no), is_directory, too_large.
#db
Go: package db (packages/native/sdk/db), on modernc.org/sqlite (no cgo).
d, err := db.Open("app") // app.db in the app data directory
res, err := d.Exec(ctx, "INSERT INTO t(a) VALUES(?)", 1)
rows, err := d.Query(ctx, "SELECT * FROM t") // []map[string]any; QueryRows keeps column order
err = d.Transaction(ctx, func(tx *db.Tx) error { _, err := tx.Exec(ctx, "..."); return err })db.Default() is the shared app.db that the UI ids and kv use. The
database opens in WAL mode with a 5 second busy timeout, foreign keys on and
write transactions that take the lock up front. The shell and a Go host child
process can use the same file at the same time.
Values are int64, float64, string, []byte (blob) and nil; a bool
binds as 0 or 1 and a date as an ISO 8601 string. In the UI a blob is a
Uint8Array. Integers beyond 2^53 lose precision in JavaScript.
SQL from the UI may not use ATTACH, DETACH or VACUUM (code
forbidden_sql), because they open or write arbitrary files. transaction
takes { sql, params? } statements and runs them all or not at all; its error
names the failing statement. Error codes: sql_error, constraint, busy.
#kv
Go: package kv (packages/native/sdk/kv), a kv(key, value) table in app.db.
s, _ := kv.Default()
err := s.SetString(ctx, "theme", "dark")
v, ok, err := s.GetString(ctx, "theme")
keys, err := s.Keys(ctx, "recent/")Values are stored as wire frames, so JSON values, bytes, dates, maps and sets
round-trip unchanged from the UI. SetWith/GetWith take wire encoder and
decoder callbacks for other types. get answers null for a missing key.
#net
Go: package sdknet (packages/native/sdk/net). The webview has fetch, so
there is no UI id.
client := sdknet.Client() // 60 s timeout, bounded dial/TLS/header waits
req, _ := http.NewRequestWithContext(ctx, "GET", url, nil)
err := sdknet.WithSecret(ctx, req, "api-token", "Authorization")WithSecret reads a secret and sets the header, so the secret never passes
through the UI. A client from Client does not forward that header to another
host on redirect.
Last updated: 2026-11-17
Contributors: Noinkin