Skip to main content
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.