Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.tinycloud.xyz/llms.txt

Use this file to discover all available pages before exploring further.

Get TinyCloud running in your browser app and store your first piece of data. By the end of this guide you will have a working app that authenticates a user, writes data to their personal space, reads it back, and generates a share link.

​
Prerequisites

Before you begin, make sure you have:
  • Node.js 18+ installed
  • A modern browser (Chrome, Firefox, Safari, Edge)
  • A wallet extension like MetaMask installed in your browser
TinyCloud uses Sign-In with Ethereum (SIWE) for authentication. Your wallet signs a message to prove ownership of your address — no transaction or gas fees required.
Do not have a wallet extension? You can use OpenKey as a passkey-based alternative to MetaMask. OpenKey manages Ethereum keys inside a TEE so users do not need a browser extension.

​
Installation

npm install @tinycloud/web-sdk
1
Initialize TinyCloud
2
Create a new TinyCloud instance in your application.
3
Quick
import { TinyCloudWeb } from '@tinycloud/web-sdk';

const tc = new TinyCloudWeb();
Explained
import { TinyCloudWeb } from '@tinycloud/web-sdk';

// Create a TinyCloud instance with configuration
// All options are optional -- sensible defaults are used
const tc = new TinyCloudWeb({
  // TinyCloud node(s) to connect to
  tinycloudHosts: ['https://node.tinycloud.xyz'],

  // Prefix for your app's space name (helps avoid collisions)
  spacePrefix: 'myapp',

  // Automatically create a space on first sign-in (default: true)
  autoCreateSpace: true,

  // Prefix prepended to all KV keys your app writes
  kvPrefix: 'myapp',

  // Show popup notifications for important events
  notifications: { popups: true },
});
4
Sign In
5
Authenticate the user by connecting their wallet and signing a message.
6
Quick
await tc.signIn();
console.log('Address:', tc.address());
Explained
// signIn() triggers the wallet connection flow:
// 1. Prompts user to connect their wallet (e.g. MetaMask)
// 2. Requests a SIWE signature to prove address ownership
// 3. Establishes an authenticated session with the TinyCloud node
// 4. Creates a space for the user if one does not exist
await tc.signIn();

// After sign-in, the user's Ethereum address is available
console.log('Address:', tc.address());
7
With autoCreateSpace: true (the default), the SDK automatically provisions a personal space for first-time users during sign-in.
8
Store Data
9
Save data to the user’s personal space via tc.kv.
10
Quick
const putResult = await tc.kv.put('profile', {
  name: 'Alice',
  joined: new Date().toISOString(),
});
if (putResult.ok) {
  console.log('Data saved!');
}
Explained
// Store a JSON object under the key 'profile'
// Data is stored in the user's space on TinyCloud
const putResult = await tc.kv.put('profile', {
  name: 'Alice',
  joined: new Date().toISOString(),
});

if (putResult.ok) {
  console.log('Data saved!');
}
// The data is now persisted and only accessible
// by this user (or those they delegate access to)
11
Retrieve Data
12
Read the data back from storage.
13
Quick
const result = await tc.kv.get('profile');
if (result.ok) {
  console.log('Retrieved:', result.data.data);
}
Explained
// Retrieve the value stored under 'profile'
const result = await tc.kv.get('profile');

// Returns the original object: { name: 'Alice', joined: '...' }
if (result.ok) {
  console.log('Retrieved:', result.data.data);
}
14
List and Delete
15
Browse keys and clean up data you no longer need.
16
Quick
const listResult = await tc.kv.list();
if (listResult.ok) {
  console.log('All keys:', listResult.data.keys);
}

const delResult = await tc.kv.del('profile');
if (delResult.ok) {
  console.log('Deleted profile');
}
Explained
// List all keys matching a prefix
// Call without arguments to list everything in the space
const listResult = await tc.kv.list();
if (listResult.ok) {
  console.log('All keys:', listResult.data.keys);
}

// Remove a key and its value
const delResult = await tc.kv.del('profile');
if (delResult.ok) {
  console.log('Deleted profile');
}
17
Share Data
18
Generate a share link so anyone can receive your data — no account required on the receiving end.
19
Quick
const result = await tc.sharing.generate({
  path: 'profile',
  expiry: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000),
});
if (result.ok) {
  console.log('Share link:', result.data.token);
}
Explained
// Generate a time-limited share link for a specific path
// The link encodes a delegation that grants read access
const result = await tc.sharing.generate({
  path: 'profile',       // The path to share
  expiry: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000), // Link expires in 7 days
});

// Share links use the tc1: prefix and can be sent
// over any channel -- chat, email, QR code, etc.
if (result.ok) {
  console.log('Share link:', result.data.token); // tc1:...
}
20
To receive shared data on the other end:
21
// Static method -- no authentication required
const result = await TinyCloudWeb.receiveShare('tc1:...');

if (result.ok) {
  console.log('Shared data:', result.data.data);
} else {
  console.error('Share expired or invalid:', result.error);
}
22
receiveShare is a static method on TinyCloudWeb. The recipient does not need to sign in or have a wallet to view shared data.

​
Complete Examples

import { TinyCloudWeb } from '@tinycloud/web-sdk';

async function main() {
  // 1. Initialize
  const tc = new TinyCloudWeb({
    notifications: { popups: true },
  });

  // 2. Sign in
  await tc.signIn();
  console.log('Address:', tc.address());

  // 3. Store data
  const putResult = await tc.kv.put('profile', {
    name: 'Alice',
    joined: new Date().toISOString(),
  });
  if (putResult.ok) {
    console.log('Data saved!');
  }

  // 4. Retrieve data
  const getResult = await tc.kv.get('profile');
  if (getResult.ok) {
    console.log('Retrieved:', getResult.data.data);
  }

  // 5. List keys
  const listResult = await tc.kv.list();
  if (listResult.ok) {
    console.log('Keys:', listResult.data.keys);
  }

  // 6. Share data
  const shareResult = await tc.sharing.generate({
    path: 'profile',
    expiry: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000),
  });
  if (shareResult.ok) {
    console.log('Share link:', shareResult.data.token);
  }

  // 7. Clean up
  const delResult = await tc.kv.del('profile');
  if (delResult.ok) {
    console.log('Deleted profile');
  }
}

main().catch(console.error);

​
Expected Output

When you run the code successfully, you should see: 
Address: 0xd8dA...6045
Data saved!
Retrieved: { name: 'Alice', joined: '2026-01-15T10:30:00.000Z' }
Keys: ['profile']
Share link: tc1:eyJhbGciOiJFZERTQ...
Deleted profile
The wallet popup will appear twice during first sign-in: once to connect, and once to sign the authentication message.

​
Configuration Reference

All options passed to new TinyCloudWeb() are optional.
OptionTypeDefaultDescription
tinycloudHostsstring[]['https://node.tinycloud.xyz']TinyCloud node URLs to connect to
spacePrefixstringundefinedPrefix for the auto-generated space name
autoCreateSpacebooleantrueCreate a space automatically on first sign-in
kvPrefixstringundefinedPrefix prepended to all KV keys
notificationsobjectundefined{ popups: true } to show browser notifications

​
Next Steps

Now that you have the basics working, explore these guides:

KV Storage

Advanced storage operations including prefixes, metadata, and data types.

Delegations

Share data access with fine-grained, revocable permissions.

Spaces

Understand spaces, the ownership containers at the heart of TinyCloud.

Node SDK

Need a backend? See the Node SDK quickstart for server-side usage.