zOS SDK Documentation

Installation

npm install @z-os/sdk

API Reference

AppManifest

Define your app's metadata and capabilities.

interface AppManifest {
  id: string;           // Unique app identifier (e.g., "ai.hanzo.myapp")
  name: string;         // Display name
  version: string;      // Semantic version (e.g., "1.0.0")
  description: string;  // Short description
  icon: string;         // Emoji or icon URL
  category: AppCategory;
  author: string;
  permissions: Permission[];
}

useApp()

React hook for accessing app context and system APIs.

import { useApp } from '@z-os/sdk';

function MyApp() {
  const { manifest, close, minimize, maximize } = useApp();

  return (
    <div>
      <h1>{manifest.name}</h1>
      <button onClick={close}>Close</button>
    </div>
  );
}

useFileSystem()

Access the virtual file system. Requires 'storage' permission.

import { useFileSystem } from '@z-os/sdk';

function FileManager() {
  const fs = useFileSystem();

  const saveFile = async () => {
    await fs.writeFile('/Documents/notes.txt', 'Hello World');
  };

  const readFile = async () => {
    const content = await fs.readFile('/Documents/notes.txt');
    console.log(content);
  };
}

useNotifications()

Send system notifications. Requires 'notifications' permission.

import { useNotifications } from '@z-os/sdk';

function NotifyButton() {
  const { send } = useNotifications();

  const notify = () => {
    send({
      title: 'Download Complete',
      body: 'Your file has been downloaded.',
      icon: '📥'
    });
  };
}

Permissions

Available permissions your app can request.

type Permission =
  | 'storage'       // Read/write files
  | 'network'       // Make network requests
  | 'notifications' // Send notifications
  | 'clipboard'     // Access clipboard
  | 'camera'        // Access camera
  | 'microphone'    // Access microphone
  | 'location'      // Access location
  | 'filesystem'    // Full filesystem access
  | 'shell'         // Execute shell commands
  | 'system';       // System-level access

Examples

Complete App Example

import React, { useState } from 'react';
import { createApp, useApp } from '@z-os/sdk';

const manifest = {
  id: 'ai.hanzo.counter',
  name: 'Counter',
  version: '1.0.0',
  description: 'A simple counter app',
  icon: '🔢',
  category: 'utilities' as const,
  author: 'Hanzo AI',
  permissions: []
};

function CounterApp() {
  const { close } = useApp();
  const [count, setCount] = useState(0);

  return (
    <div className="p-4 h-full flex flex-col items-center justify-center">
      <h1 className="text-6xl font-bold mb-8">{count}</h1>
      <div className="flex gap-4">
        <button
          onClick={() => setCount(c => c - 1)}
          className="px-6 py-3 bg-red-500 rounded-lg"
        >
          -1
        </button>
        <button
          onClick={() => setCount(c => c + 1)}
          className="px-6 py-3 bg-green-500 rounded-lg"
        >
          +1
        </button>
      </div>
    </div>
  );
}

export default createApp(manifest, CounterApp);

Related Packages

@z-os/ui @z-os/apps @z-os/desktop