Installation

This guide covers installing the L{CORE} SDK and setting up your development environment.

SDK Installation

Node.js / TypeScript

npm install @locale/lcore-sdk
# or
yarn add @locale/lcore-sdk
# or
pnpm add @locale/lcore-sdk

Python

pip install lcore-sdk

Development Requirements

For SDK Development

Requirement	Version	Notes
Node.js	18+	For TypeScript/JavaScript SDK
Python	3.9+	For Python SDK
Git	Latest	Version control

For On-Chain Attestation Features

If you plan to deploy your own attestation infrastructure (Cartesi node + Attestor), you'll need additional tooling:

Requirement	Purpose
Docker Desktop	Building and running containers
Cartesi CLI	Building Cartesi machines

Install the Cartesi CLI:

npm install -g @cartesi/cli

See the Cartesi Get Started guide for complete prerequisites.

Platform Requirements for Deployment

Apple Silicon Users (M1/M2/M3)

When building Docker images for cloud deployment (EigenCloud, AWS, GCP, etc.), you must specify --platform linux/amd64.

Cloud infrastructure typically runs on AMD64 (x86_64) architecture. Images built on Apple Silicon default to ARM64 and will fail with exec format error.

Configure Docker for Cross-Platform Builds

# Create a builder for multi-platform support
docker buildx create --name multiplatform --use

# Verify the builder is ready
docker buildx inspect --bootstrap

Always Use Platform Flag

# Correct: Specify platform
docker build --platform linux/amd64 -f Dockerfile -t your-image .

# Incorrect: Omitting platform on Apple Silicon
docker build -f Dockerfile -t your-image .  # Will be ARM64!

Environment Setup

API Keys

For SDK usage, create a .env file in your project:

# Required for authenticated API calls
LCORE_API_KEY=your-api-key

# Target network environment
LCORE_NETWORK=testnet

Get an API key from the Locale Dashboard.

Encryption Keys (Deployment Only)

If you're deploying your own attestation infrastructure, you'll need to configure encryption keys. See Encryption Key Configuration for detailed setup instructions.

Verify Installation

TypeScript/JavaScript

import { LCore } from '@locale/lcore-sdk';

const lcore = new LCore({
  apiKey: process.env.LCORE_API_KEY,
  network: 'testnet',
});

// Check connection
const health = await lcore.health();
console.log('SDK Status:', health.status);

Python

from lcore_sdk import LCore
import os

lcore = LCore(
    api_key=os.environ.get('LCORE_API_KEY'),
    network='testnet'
)

# Check connection
health = lcore.health()
print(f"SDK Status: {health['status']}")

Project Structure

A typical L{CORE} project structure:

my-lcore-project/
├── src/
│   ├── index.ts          # Application entry point
│   ├── devices/          # Device registration logic
│   ├── streams/          # Data stream handlers
│   └── attestations/     # Attestation logic
├── .env                  # Environment variables (gitignore this!)
├── .env.example          # Example environment file
├── package.json
└── tsconfig.json

Development vs Production

Environment	API Key Required	Encryption Keys	Infrastructure
Development	Optional (rate limited)	Not needed	Use managed services
Staging	Yes	Optional	Can self-host or use managed
Production	Yes	Required for privacy	Self-host for full control

For production deployments with privacy requirements, see the Deployment section.

Troubleshooting Installation

"Module not found" Error

Ensure you've installed the SDK:

npm list @locale/lcore-sdk

If not listed, reinstall:

npm install @locale/lcore-sdk

TypeScript Type Errors

The SDK includes TypeScript definitions. If you see type errors, ensure your tsconfig.json includes:

{
  "compilerOptions": {
    "moduleResolution": "node",
    "esModuleInterop": true
  }
}

Cartesi CLI Not Found

If npx cartesi fails:

# Install globally
npm install -g @cartesi/cli

# Or use npx (downloads if needed)
npx @cartesi/cli --version

See Cartesi CLI documentation for more options.

Next Steps

• Configuration — Configure your project settings
• First Attestation — Build your first attestation
• Deployment — Deploy to production (when ready)