SDK Quickstart

Synodes provides official SDKs for Python and TypeScript with identical capabilities: sandbox lifecycle management, file system operations, Git integration, language server protocol support, and process execution. Every sandbox can be provisioned with auto-injected Turso database credentials for agent memory.

Python SDK

Installation

pip install synodes

Configuration

Configure the SDK via environment variables or a config object:

from synodes import Synodes, SynodesConfig

# Environment variables: SYNODES_API_KEY, SYNODES_API_URL, SYNODES_TARGET
synodes = Synodes()

# Or explicit config
config = SynodesConfig(
    api_key="syn_...",
    api_url="https://api.synodes.io",
    target="us"
)
synodes = Synodes(config)

Create a Sandbox

sandbox = synodes.create(language="python")

# With custom resources
from synodes import Resources
sandbox = synodes.create(
    language="python",
    resources=Resources(cpu=4, memory=8192, disk=20)
)

# Ephemeral — auto-deleted on stop
sandbox = synodes.create(ephemeral=True, auto_stop_interval=5)

Execute Code

# Shell command
response = sandbox.process.exec('echo "Hello, World!"')
print(response.result)

# Python code
response = sandbox.process.code_run('''
x = 10
y = 20
print(f"Sum: {x + y}")
''')
print(response.result)

File & Git Operations

# Upload / download files
sandbox.fs.upload_file(b'Hello, World!', 'path/to/file.txt')
content = sandbox.fs.download_file('path/to/file.txt')

# Clone a repo
sandbox.git.clone('https://github.com/example/repo', 'path/to/clone')
branches = sandbox.git.branches('path/to/repo')

TypeScript SDK

Installation

npm install @synodes/sdk
# or
yarn add @synodes/sdk

Configuration

import { Synodes } from '@synodes/sdk';

// Environment variables: SYNODES_API_KEY, SYNODES_API_URL, SYNODES_TARGET
const synodes = new Synodes();

// Or explicit config
const synodes = new Synodes({
  apiKey: 'syn_...',
  apiUrl: 'https://api.synodes.io',
  target: 'us',
});

Create a Sandbox

const sandbox = await synodes.create({ language: 'typescript' });

// With custom resources
const sandbox = await synodes.create({
  language: 'python',
  resources: { cpu: 4, memory: 8192, disk: 20 }
});

// Ephemeral
const sandbox = await synodes.create({
  ephemeral: true,
  autoStopInterval: 5
});

Execute Code

// Shell command
const response = await sandbox.process.executeCommand('echo "Hello, World!"');
console.log(response.result);

// TypeScript code
const response = await sandbox.process.codeRun(`
const x = 10;
const y = 20;
console.log(\`Sum: \${x + y}\`);
`);
console.log(response.result);

File & Git Operations

// Upload / download files
await sandbox.fs.uploadFile(Buffer.from('Hello, World!'), 'path/to/file.txt');
const content = await sandbox.fs.downloadFile('path/to/file.txt');

// Clone a repo
await sandbox.git.clone('https://github.com/example/repo', 'path/to/clone');
const branches = await sandbox.git.branches('path/to/repo');

Agent Memory with Turso

Every sandbox gets TURSO_DATABASE_URL and TURSO_AUTH_TOKEN environment variables injected at creation time. Your agent can use these to persist state, store conversation history, or cache results in a serverless SQLite-compatible database.

Python Example

import os
import libsql_client

# Agent reads the injected env vars
url = os.environ["TURSO_DATABASE_URL"]
token = os.environ["TURSO_AUTH_TOKEN"]

client = libsql_client.create_client(url=url, auth_token=token)

# Create a memory table
client.execute("""
    CREATE TABLE IF NOT EXISTS agent_memory (
        id INTEGER PRIMARY KEY AUTOINCREMENT,
        key TEXT UNIQUE,
        value TEXT,
        updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
    )
""")

# Store a memory
client.execute(
    "INSERT OR REPLACE INTO agent_memory (key, value) VALUES (?, ?)",
    ["last_user_query", "What is the capital of France?"]
)

# Recall a memory
result = client.execute(
    "SELECT value FROM agent_memory WHERE key = ?",
    ["last_user_query"]
)
print(result.rows[0][0])  # "What is the capital of France?"

TypeScript Example

import { createClient } from '@libsql/client';

// Agent reads the injected env vars
const url = process.env.TURSO_DATABASE_URL!;
const token = process.env.TURSO_AUTH_TOKEN!;

const client = createClient({ url, authToken: token });

// Create a memory table
await client.execute(`
  CREATE TABLE IF NOT EXISTS agent_memory (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    key TEXT UNIQUE,
    value TEXT,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
  )
`);

// Store a memory
await client.execute({
  sql: 'INSERT OR REPLACE INTO agent_memory (key, value) VALUES (?, ?)',
  args: ['last_user_query', 'What is the capital of France?']
});

// Recall a memory
const result = await client.execute({
  sql: 'SELECT value FROM agent_memory WHERE key = ?',
  args: ['last_user_query']
});
console.log(result.rows[0].value); // "What is the capital of France?"

Language Server Protocol (LSP)

Both SDKs support creating LSP servers inside sandboxes for code completions, diagnostics, and document symbols:

# Python
lsp = sandbox.create_lsp_server('python', 'path/to/project')
lsp.start()
lsp.did_open('path/to/file.py')
completions = lsp.completions('path/to/file.py', {"line": 10, "character": 15})

// TypeScript
const lsp = await sandbox.createLspServer('typescript', 'path/to/project');
await lsp.start();
await lsp.didOpen('path/to/file.ts');
const completions = await lsp.completions('path/to/file.ts', { line: 10, character: 15 });