OSE Cloud SDK

Official TypeScript/JavaScript SDK for OSE Cloud Platform - Build, deploy, and manage containerized applications with AI-powered sandboxes.

Features

• Sandboxes - Create isolated development environments
• Deployments - Deploy applications to production
• Chats - AI-powered chat interface
• Usage Tracking - Monitor your resource consumption
• Type-Safe - Full TypeScript support
• Modern - ESM and CommonJS support

Installation

npm install @ose-cloud/sdk
# or
pnpm add @ose-cloud/sdk
# or
yarn add @ose-cloud/sdk

Quick Start

import { OSE } from '@ose-cloud/sdk';

// Initialize with your API key
const ose = new OSE({
  apiKey: 'your-api-key-here'
});

// Create a sandbox
const sandbox = await ose.sandboxes.create({
  name: 'my-project',
  template: 'nextjs'
});

console.log('Sandbox created:', sandbox.id);

Getting an API Key

1. Visit www.ose.sh
2. Sign in to your account
3. Navigate to Dashboard → API Keys
4. Create a new API key with the permissions you need

Available Permissions:

• sandbox:create - Create new sandboxes
• sandbox:read - List and view sandboxes
• sandbox:execute - Run commands in sandboxes
• sandbox:delete - Delete sandboxes
• files:read - Read files from sandboxes
• files:write - Write files to sandboxes
• deploy:create - Create deployments
• deploy:read - View deployments
• usage:read - View usage statistics
• chat:create - Create chat sessions
• chat:read - View chat history

API Reference

Initialization

const ose = new OSE({
  apiKey: 'your-api-key',
  baseUrl?: 'https://www.ose.sh/api', // Optional, defaults to production
  timeout?: 60000, // Optional, request timeout in ms
  maxRetries?: 3 // Optional, max retries for failed requests
});

Sandboxes

Available Templates

Choose from these pre-configured environments when creating a sandbox:

| Template | Environment | Best For | |----------|-------------|----------| | nextjs | Node.js 20 + npm + yarn | Next.js, React SSR apps | | react | Node.js 20 + Vite | Client-side React apps | | vue | Node.js 20 + Vite | Vue.js 3 applications | | svelte | Node.js 20 + SvelteKit | Svelte applications | | expo | Node.js 20 + Expo CLI | React Native mobile apps | | python | Python 3.12 + pip | Data science, ML, APIs | | fullstack | Node.js + Python + DB tools | Full-stack development |

Create a sandbox

const sandbox = await ose.sandboxes.create({
  name: 'my-app',
  template: 'nextjs', // Choose from templates above
  metadata?: { key: 'value' },
  envs?: { NODE_ENV: 'development' },
  timeoutMS?: 300000,
  port?: 3000
});

List sandboxes

const sandboxes = await ose.sandboxes.list({
  status?: 'running' // Optional filter
});

Connect to a sandbox

const sandbox = ose.sandboxes.connect('sandbox-id');

// Get sandbox info
const info = await sandbox.getInfo();

// Write files
await sandbox.files.write('/workspace/index.js', 'console.log("Hello")');

// Read files
const content = await sandbox.files.read('/workspace/index.js');

// List files
const files = await sandbox.files.list('/workspace');

// Run commands
const result = await sandbox.commands.run('npm install');
console.log(result.stdout);

// Delete sandbox
await sandbox.delete();

Deployments

Create a deployment

const deployment = await ose.deployments.create({
  name: 'my-production-app',
  sandboxId: 'sandbox-id',
  projectType: 'nextjs',
  port: 3000,
  customDomain?: 'app.example.com',
  buildCommand?: 'npm run build',
  installCommand?: 'npm install',
  startCommand?: 'npm start',
  environmentVariables?: {
    DATABASE_URL: 'postgres://...'
  }
});

console.log('Deployed to:', deployment.url);

List deployments

const deployments = await ose.deployments.list();

Manage a deployment

const deployment = ose.deployments.connect('deployment-id');

// Get deployment info
const info = await deployment.getInfo();

// Get logs
const logs = await deployment.logs.get(100); // Last 100 lines

// Restart deployment
await deployment.restart();

// Stop deployment
await deployment.stop();

// Delete deployment
await deployment.delete();

Chats

Create a chat

const chat = await ose.chats.create({
  title: 'Project Discussion'
});

List chats

const chats = await ose.chats.list();

Usage

Get usage statistics

const usage = await ose.usage.get();
console.log('Total requests:', usage.totalRequests);
console.log('Total cost:', usage.totalCost);

Examples

Deploy a Next.js App

import { OSE } from '@ose-cloud/sdk';

async function deployNextApp() {
  const ose = new OSE({ apiKey: process.env.OSE_API_KEY! });

  // Create sandbox
  const sandbox = await ose.sandboxes.create({
    name: 'my-nextjs-app',
    template: 'nextjs'
  });

  console.log('Sandbox created:', sandbox.id);

  // Connect and add files
  const sb = ose.sandboxes.connect(sandbox.id);

  await sb.files.write('/workspace/package.json', JSON.stringify({
    name: 'my-app',
    scripts: {
      dev: 'next dev',
      build: 'next build',
      start: 'next start'
    },
    dependencies: {
      next: '^14.0.0',
      react: '^18.0.0',
      'react-dom': '^18.0.0'
    }
  }, null, 2));

  await sb.files.write('/workspace/app/page.tsx', `
export default function Home() {
  return <div>Hello from OSE Cloud!</div>
}
  `);

  // Deploy
  const deployment = await ose.deployments.create({
    name: 'my-nextjs-app',
    sandboxId: sandbox.id,
    port: 3000
  });

  console.log('Deployed to:', deployment.url);
}

deployNextApp().catch(console.error);

Run Commands in Sandbox

import { OSE } from '@ose-cloud/sdk';

async function runCommands() {
  const ose = new OSE({ apiKey: process.env.OSE_API_KEY! });

  const sandbox = await ose.sandboxes.create({
    name: 'test-environment',
    template: 'node'
  });

  const sb = ose.sandboxes.connect(sandbox.id);

  // Install dependencies
  const install = await sb.commands.run('npm install express');
  console.log('Install output:', install.stdout);

  // Run a script
  await sb.files.write('/workspace/server.js', `
    const express = require('express');
    const app = express();
    app.get('/', (req, res) => res.send('Hello!'));
    app.listen(3000, () => console.log('Server started'));
  `);

  const run = await sb.commands.run('node server.js', {
    background: true
  });

  // Cleanup
  await sb.delete();
}

runCommands().catch(console.error);

Error Handling

import { OSE, APIError } from '@ose-cloud/sdk';

try {
  const ose = new OSE({ apiKey: 'invalid-key' });
  await ose.sandboxes.list();
} catch (error) {
  if (error instanceof Error) {
    const apiError = error as APIError;
    console.error('Error:', apiError.message);
    console.error('Status:', apiError.status);
    console.error('Details:', apiError.details);
  }
}

TypeScript Support

The SDK is written in TypeScript and provides full type definitions:

import { OSE, Sandbox, Deployment, SandboxInfo } from '@ose-cloud/sdk';

const ose: OSE = new OSE({ apiKey: 'key' });
const sandbox: Sandbox = await ose.sandboxes.create({ name: 'test' });
const info: SandboxInfo = await ose.sandboxes.connect(sandbox.id).getInfo();

Rate Limits

API keys have their own rate limiting. If you exceed the limit, you'll receive a 429 Too Many Requests error with a retryAfter field indicating when you can retry.

Support

• Email: [email protected]
• Documentation: https://www.ose.sh/docs
• Discord: https://discord.gg/ose-cloud
• Issues: https://github.com/ose-cloud/sdk/issues

License

MIT © OSE Cloud