Node SDK Quickstart

Get TinyCloud running in a Node.js environment and store your first piece of data. By the end of this guide you will have a working script that authenticates with a private key, reads and writes to a space, and creates a delegation for another user.

Prerequisites

Before you begin, make sure you have:

Node.js 18+ installed
An Ethereum private key (32-byte hex string) for authenticated mode, or nothing at all for session-only mode

Never hardcode private keys in your source code. Always use environment variables or a secrets manager.

Installation

npm install @tinycloud/node-sdk

Configure Environment

Set up your private key as an environment variable.

TINYCLOUD_PRIVATE_KEY=0x0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

For development, you can generate a test private key using: node -e "console.log('0x' + require('crypto').randomBytes(32).toString('hex'))"

Initialize TinyCloud

Create a TinyCloud instance with your configuration.

Quick

import { TinyCloudNode } from '@tinycloud/node-sdk';

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

Explained

import { TinyCloudNode } from '@tinycloud/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 KV keys
  prefix: 'myapp',

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

Authenticate with the TinyCloud network.

Quick

await tc.signIn();
console.log('Space:', tc.spaceId);
console.log('DID:', tc.did); // did:pkh:eip155:1:0x...

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 with the TinyCloud node
// 4. Creates a space for you if one does not exist
await tc.signIn();

// After sign-in, your space ID and DID are available
console.log('Space:', tc.spaceId);

// tc.did returns your primary DID (user identity)
console.log('DID:', tc.did); // did:pkh:eip155:1:0x...

Store Data

Save data to your space using the key-value store via tc.kv.

Quick

const putResult = await tc.kv.put('config', {
  version: '1.0.0',
  lastUpdated: new Date().toISOString(),
});
if (putResult.ok) {
  console.log('Data saved!');
}

Explained

// Store a JSON object under the key 'config'
const putResult = await tc.kv.put('config', {
  version: '1.0.0',
  lastUpdated: new Date().toISOString(),
});

if (putResult.ok) {
  console.log('Data saved!');
}
// Data is now stored in your space on TinyCloud

Retrieve Data

Read the data back from storage.

Quick

const result = await tc.kv.get('config');
if (result.ok) {
  console.log('Retrieved:', result.data.data);
}

Explained

// Retrieve the value stored under 'config'
const result = await tc.kv.get('config');

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

List and Delete

Browse keys and remove data you no longer need.

Quick

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

const delResult = await tc.kv.del('config');
if (delResult.ok) {
  console.log('Deleted config');
}

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('config');
if (delResult.ok) {
  console.log('Deleted config');
}

Complete Example

Here is the full working code:

index.ts

import { TinyCloudNode } from '@tinycloud/node-sdk';

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

  // 2. Sign in
  await tc.signIn();
  console.log('Space:', tc.spaceId);
  console.log('DID:', tc.did);

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

  // 4. Retrieve data
  const getResult = await tc.kv.get('config');
  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. Clean up
  const delResult = await tc.kv.del('config');
  if (delResult.ok) {
    console.log('Deleted config');
  }
}

main().catch(console.error);

Run with:

TINYCLOUD_PRIVATE_KEY=0x... npx ts-node index.ts

Expected Output

When you run the code successfully, you should see:

Space: tinycloud:pkh:eip155:1:0xd8dA...6045:myapp
DID: did:pkh:eip155:1:0xd8dA...6045
Data saved!
Retrieved: { version: '1.0.0', lastUpdated: '2026-01-15T10:30:00.000Z' }
Keys: ['config']
Deleted config

Session-Only Mode

You can create a TinyCloud instance without a private key. This is useful for clients that only need to receive delegations from other users, not own a space.

Quick
Explained

const bob = new TinyCloudNode();

console.log(bob.did);            // did:key:z6Mk... (session key DID)
console.log(bob.isSessionOnly);  // true

// No config required -- a session key is generated automatically
const bob = new TinyCloudNode();

// In session-only mode, .did returns a session key DID
// (since there is no primary identity to authenticate with)
console.log(bob.did);            // did:key:z6Mk...
console.log(bob.isSessionOnly);  // true

// Session-only clients cannot create spaces or write
// to their own storage, but they CAN receive delegations
// from other users and access delegated data

Session-only clients generate an ephemeral did:key identity. They can receive delegations and read/write to other users’ spaces, but they do not have their own space.

Delegations

Grant another user or service scoped access to your space.

After signIn, tc.did returns your primary DID (the identity you authenticated with). Before signIn, it returns your session key DID. For delegations, always use the recipient’s primary DID (their tc.did after they’ve signed in).

Quick
Explained

// Alice creates a delegation for Bob (after Bob has signed in)
const delegation = await alice.createDelegation({
  delegateDID: bob.did,
  path: 'shared/',
  actions: ['tinycloud.kv/get', 'tinycloud.kv/put'],
});

// Bob uses the delegation to access Alice's data
const access = await bob.useDelegation(delegation);
const result = await access.kv.get('shared/data');
if (result.ok) {
  console.log(result.data.data);
}

// Alice grants Bob access to her 'shared/' prefix
const delegation = await alice.createDelegation({
  // Bob's primary DID (tc.did after signIn)
  // This is the identity Bob authenticated with
  delegateDID: bob.did,

  // Path prefix the delegation covers
  path: 'shared/',

  // Specific actions Bob is allowed to perform
  actions: ['tinycloud.kv/get', 'tinycloud.kv/put'],
});

// Bob loads the delegation and gets a scoped client
const access = await bob.useDelegation(delegation);

// Bob can now read and write under Alice's 'shared/' prefix
const getResult = await access.kv.get('shared/data');
if (getResult.ok) {
  console.log(getResult.data.data);
}
const putResult = await access.kv.put('shared/response', { message: 'Thanks!' });
if (putResult.ok) {
  console.log('Response saved!');
}

DID Reference

The Node SDK exposes different DIDs depending on authentication state:

Property	Before signIn	After signIn	Session-only mode
`tc.did`	Session DID	Primary DID	Session DID
`tc.sessionDid`	Session DID	Session DID	Session DID

tc.address is undefined until signIn() completes.

Session Persistence

By default, sessions are stored in memory and lost when your process exits. For long-running services, use file-based session storage.

Memory (Default)
File Storage

import { TinyCloudNode, MemorySessionStorage } from '@tinycloud/node-sdk';

const tc = new TinyCloudNode({
  privateKey: process.env.TINYCLOUD_PRIVATE_KEY,
  host: 'https://node.tinycloud.xyz',
  // Explicit but not required -- memory storage is the default
  sessionStorage: new MemorySessionStorage(),
});

import { TinyCloudNode, FileSessionStorage } from '@tinycloud/node-sdk';

const tc = new TinyCloudNode({
  privateKey: process.env.TINYCLOUD_PRIVATE_KEY,
  host: 'https://node.tinycloud.xyz',
  // Persists the session to disk so it survives process restarts
  sessionStorage: new FileSessionStorage('./.tinycloud-session'),
});

File-based storage is recommended for production services to avoid re-authentication on every restart. Add the session file to your .gitignore.

Configuration Reference

All options passed to new TinyCloudNode() are optional. Omitting everything creates a session-only client.

Option	Type	Default	Description
`privateKey`	`string`	`undefined`	Ethereum private key (hex). Omit for session-only mode
`host`	`string`	`'https://node.tinycloud.xyz'`	TinyCloud node URL
`prefix`	`string`	`undefined`	Prefix prepended to all KV keys
`autoCreateSpace`	`boolean`	`false`	Create a space automatically on first sign-in
`sessionStorage`	`SessionStorage`	`MemorySessionStorage`	Where to persist session state

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.

Web SDK

Building a frontend? See the Web SDK quickstart for browser usage.

Getting Started

Guides

Concepts

Node SDK Quickstart

Prerequisites

Installation

Complete Example

Expected Output

Session-Only Mode

Delegations

DID Reference

Session Persistence

Configuration Reference

Next Steps

KV Storage

Delegations

Spaces

Web SDK

Getting Started

Guides

Concepts

​Prerequisites

​Installation

​Complete Example

​Expected Output

​Session-Only Mode

​Delegations

​DID Reference

​Session Persistence

​Configuration Reference

​Next Steps

KV Storage

Delegations

Spaces

Web SDK

Prerequisites

Installation

Complete Example

Expected Output

Session-Only Mode

Delegations

DID Reference

Session Persistence

Configuration Reference

Next Steps