Skip to main content
Get TinyCloud running in a Node.js environment and store your first piece of data.

​
Prerequisites

Before you begin, make sure you have:
  • Node.js 18+ installed
  • An Ethereum private key (32-byte hex string)
Never hardcode private keys in your source code. Always use environment variables or a secrets manager.

​
Installation

Install the TinyCloud Node SDK:
npm
npm install @tinycloudlabs/node-sdk
1
Configure Environment
2
Set up your private key as an environment variable.
3
TINYCLOUD_PRIVATE_KEY=0x0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
4
For development, you can generate a test private key using: node -e "console.log('0x' + require('crypto').randomBytes(32).toString('hex'))"
5
Initialize TinyCloud
6
Create a TinyCloud instance with your configuration.
7
Quick
import { TinyCloudNode } from '@tinycloudlabs/node-sdk';

const tc = new TinyCloudNode({
  privateKey: process.env.TINYCLOUD_PRIVATE_KEY,
  host: 'https://node.tinycloud.xyz',
  prefix: 'myapp'
});
Explained
import { TinyCloudNode } from '@tinycloudlabs/node-sdk';

const tc = new TinyCloudNode({
  // Your Ethereum private key (from environment variable)
  privateKey: process.env.TINYCLOUD_PRIVATE_KEY,
  // The TinyCloud node to connect to
  host: 'https://node.tinycloud.xyz',
  // Optional: prefix for all your keys (useful for multi-tenant apps)
  prefix: 'myapp'
});
8
Sign In
9
Authenticate with the TinyCloud network.
10
Quick
await tc.signIn();
console.log('Signed in successfully');
Explained
// signIn() authenticates using your private key:
// 1. Derives your Ethereum address from the private key
// 2. Signs a SIWE message to prove ownership
// 3. Establishes an authenticated session
await tc.signIn();

console.log('Signed in successfully');
11
Store Data
12
Save data to your space using the key-value store.
13
Quick
await tc.kv.put('config', {
  version: '1.0.0',
  lastUpdated: new Date().toISOString()
});
console.log('Data saved!');
Explained
// Store a JSON object under the key 'config'
// Note: Node SDK uses tc.kv (not tc.storage like Web SDK)
await tc.kv.put('config', {
  version: '1.0.0',
  lastUpdated: new Date().toISOString()
});

console.log('Data saved!');
// Data is now stored in your space on TinyCloud
14
Retrieve Data
15
Read the data back from storage.
16
Quick
const config = await tc.kv.get('config');
console.log('Retrieved:', config);
Explained
// Retrieve the data stored under 'config'
const config = await tc.kv.get('config');

// Returns the original object: { version: '1.0.0', lastUpdated: '...' }
console.log('Retrieved:', config);

​
Complete Example

Here is the full working code:
index.ts
import { TinyCloudNode } from '@tinycloudlabs/node-sdk';

async function main() {
  // Initialize
  const tc = new TinyCloudNode({
    privateKey: process.env.TINYCLOUD_PRIVATE_KEY,
    host: 'https://node.tinycloud.xyz',
    prefix: 'myapp'
  });

  // Sign in
  await tc.signIn();
  console.log('Signed in successfully');

  // Store data
  await tc.kv.put('config', {
    version: '1.0.0',
    lastUpdated: new Date().toISOString()
  });
  console.log('Data saved!');

  // Retrieve data
  const config = await tc.kv.get('config');
  console.log('Retrieved:', config);
}

main().catch(console.error);
Run with: 
TINYCLOUD_PRIVATE_KEY=0x... npx ts-node index.ts

​
Session Persistence

By default, sessions are stored in memory and lost when your process exits. For long-running services, use file-based session storage. 
import { TinyCloudNode, MemorySessionStorage } from '@tinycloudlabs/node-sdk';

const tc = new TinyCloudNode({
  privateKey: process.env.TINYCLOUD_PRIVATE_KEY,
  host: 'https://node.tinycloud.xyz',
  sessionStorage: new MemorySessionStorage()
});
File-based storage is recommended for production services to avoid re-authentication on every restart.

​
Expected Output

When you run the code successfully, you should see: 
Signed in successfully
Data saved!
Retrieved: { version: '1.0.0', lastUpdated: '2024-01-15T10:30:00.000Z' }

​
Next Steps

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

Storage Guide

Learn about advanced storage operations and data types.

Delegation

Share data access with other users or services.

Concepts

Understand spaces, capabilities, and the TinyCloud architecture.

API Reference

Full API documentation for all SDK methods.