App SDK - uOS

Load the SDK from the uOS host. Call uOS.ready() when your UI is ready. That dismisses the loading splash.

<script src="https://www.uos.agency/uos-app-sdk.js"></script>
<script>
  (async () => {
    await uOS.ready();
    const ctx = await uOS.getContext();
    // {
    //   host: 'uOS',
    //   appId: string,
    //   user: { address: string | null },
    //   theme: 'light' | 'dark',
    //   locale: string
    // }
  })();
</script>

The file is served from the uOS origin as /uos-app-sdk.js (for example https://www.uos.agency/uos-app-sdk.js). Your app still renders without the SDK. The splash also clears on the iframe load event, but you get no wallet, context, or window control through the bridge.

API

Method	Permission	Description
`uOS.ready()`	none	Hide the splash; signal successful boot. Returns `{ ok: true }`
`uOS.getContext()`	none	`{ host: 'uOS', appId, user: { address }, theme, locale }`. `address` is `null` when no wallet is connected; `theme` is `'light'` or `'dark'`; `locale` is the host `navigator.language` (fallback `'en-US'`)
`uOS.openUrl(url)`	none	Ask uOS to open an `http:`/`https:` URL in a new tab. Returns `{ ok: true }` when `url` is a string (non-http(s) URLs are ignored by the shell)
`uOS.close()`	none	Close this app window. Returns `{ ok: true }`
`uOS.wallet.request({ method, params })`	`wallet:request` (+ `wallet:sign` for writes)	EIP-1193-style request
`uOS.fs.read(path)`	`filesystem:read`	Read from `/apps/<appId>/…`. Returns `{ content }` (`content` is `null` if the path is missing or not a file)
`uOS.fs.write(path, content)`	`filesystem:write`	Write under that directory. Returns `{ ok: boolean }`
`uOS.fs.list(path)`	`filesystem:read`	List that directory (`path` defaults to `/`). Returns `{ entries }` (empty array if the directory is missing)
`uOS.net.fetch({ url, method, headers, body })`	`network:fetch`	Host-mediated public http(s) fetch. Returns `{ status, body }`. Disallowed/missing URL → `-32602`; timeout/network failure → `4900`
`uOS.agents.call(payload)`	`agents:call`	Not implemented yet; returns `4100` without permission, `4200` when granted
`uOS.storage.ipfs(payload)`	`storage:ipfs`	Not implemented yet; returns `4100` without permission, `4200` when granted
`uOS.on(event, fn)`	none	Subscribe to host events. The host does not emit events yet

net.fetch allows public http:/https: URLs only (SSRF-guarded: no localhost, private, link-local, or userinfo URLs), does not follow redirects (redirect: 'error'), sends credentials: 'omit', times out after 10 seconds, and caps the response body at 256 KB. Only method: 'POST' is sent as POST; any other method (including omitted) is sent as GET. Filesystem paths are relative to the app’s private directory. Path segments of .. are rejected (-32602). entry.url must not resolve to the uOS shell origin — the host refuses to embed same-origin apps.

Wallet

When embedded in uOS, route wallet calls through the bridge so the user’s session is reused and every write gets a consent sheet above your iframe:

const embedded = window.parent !== window && window.uOS;

async function getAccounts() {
  if (embedded) {
    return uOS.wallet.request({ method: "eth_requestAccounts" });
  }
  return myOwnConnector.request({ method: "eth_requestAccounts" });
}

Read methods (need wallet:request only; no consent sheet):

eth_accounts
eth_requestAccounts
eth_chainId
net_version

eth_accounts and eth_requestAccounts are answered from the connected wagmi address (or [] if disconnected) without calling the provider. Everything else (including personal_sign, eth_sendTransaction, typed data) needs wallet:sign and per-request approval. Rejection rejects the promise with an Error whose .code is 4001.

Error codes

Code	Meaning
`4001`	User rejected the request
`4100`	Permission not granted in your manifest (or not consented)
`4200`	Capability not implemented by this host version
`4900`	Wallet, filesystem, or `net.fetch` unavailable (no provider, missing FS module, timeout/network error)
`-32601`	Unknown method
`-32602`	Malformed params (invalid path, disallowed `net.fetch` URL, missing required fields)

Runtime

Your app runs in:

<iframe
  sandbox="allow-scripts allow-forms allow-popups allow-modals allow-same-origin"
  allow="clipboard-write"
>

on your origin. The host validates event.origin against your entry.url origin and event.source against your iframe. Wallet consent sheets render in the uOS window chrome above the iframe, so your app cannot cover them.

Publish to the App Store when your manifest and SDK are ready.

​API

​Wallet

​Error codes

​Runtime

​Next

API

Wallet

Error codes

Runtime

Next