# Oblien Documentation

> Oblien provides isolated, secure virtual machines for AI agents - boot in milliseconds, full root access, real networking, encrypted storage.
> For the raw markdown of any page below, fetch its URL with a `.md` suffix (e.g. /docs/cdn/overview.md).

## overview

- [Architecture](/docs/architecture.md): How Oblien isolates workspaces using Firecracker microVMs and Docker images - hardware-level security with container-level developer experience.
- [Overview](/docs.md): Cloud workspaces for AI agents, services, and development. Hardware-isolated microVMs that boot in milliseconds - drive them from the API, MCP, or the dashboard.
- [Build a SaaS or VM reseller](/docs/saas-reselling.md): Customer namespaces, resource caps, independent checkout pricing and allowances, secure billing portals, and payment reconciliation
- [Security & Privacy](/docs/security.md): Two-layer security (network firewall + token auth), hardware isolation, and zero-access architecture - built for agents running untrusted code.
- [Use Cases](/docs/use-cases.md): Architecture patterns for workspaces - AI agents, service hosting, remote development, SaaS sandboxes, and parallel compute.
- [Workspace Networking](/docs/workspace-networking.md): How workspaces communicate with each other, how the network is protected, and when to use workspace-to-workspace calls

## workspace

- [Audit history](/docs/workspace/audit.md): See who changed a workspace, when it happened, and the result.
- [Authentication](/docs/workspace/authentication.md): API keys, tokens, and authentication methods
- [Dashboard](/docs/workspace/dashboard.md): Managing workspaces through the Oblien dashboard
- [Remote desktop](/docs/workspace/desktop.md): Create saved desktops with a chosen resolution and connect in your browser or VNC app
- [Persistent disks](/docs/workspace/disks.md): Attach persistent storage, share prepared software, and reuse root disks across workspaces
- [Domains](/docs/workspace/domains.md): Custom domains, free preview URLs, and branded subdomains
- [Errors](/docs/workspace/errors.md): Error codes and troubleshooting guide
- [Native guest runtimes](/docs/workspace/guest-runtimes.md): Select an image's native runtime through the existing workspace APIs
- [Introduction](/docs/workspace.md): Cloud workspaces for AI agents, services, and development. Hardware-isolated microVMs you can create, control, and destroy through code.
- [macOS workspaces](/docs/workspace/macos.md): Configure Mac resources, native terminal and files, optional desktop access, and reusable images
- [Sleep and wake on request](/docs/workspace/on-demand.md): Let an HTTP app sleep when idle and wake through its public URL, with configurable idle time and memory retention
- [Quickstart](/docs/workspace/quickstart.md): Create your first workspace in 5 minutes
- [SDK Setup](/docs/workspace/sdk-setup.md): Install and configure the Oblien Workspace SDK
- [Sharing and account access](/docs/workspace/sharing.md): Invite collaborators, choose their permissions, and open shared workspaces using your own login.

## api

- [Analytics](/docs/api/analytics.md): Traffic analytics, bandwidth metrics, geo breakdown, request logs, and live streaming for your domains
- [Billing](/docs/api/billing.md): Namespace-bound billing — sell plans, entitle credits, and enforce quotas without touching Stripe
- [Domains](/docs/api/domains.md): Custom domain and SSL management API
- [Edge Proxy](/docs/api/edge-proxy.md): Reverse proxy — route subdomains to verified external upstreams
- [Edge Tunnel](/docs/api/edge-tunnel.md): Expose local ports to the internet through the Oblien edge
- [Images](/docs/api/images.md): Browse the available workspace image catalog
- [Overview](/docs/api.md): Complete API reference for Oblien Workspace
- [Lifecycle & Power](/docs/api/lifecycle.md): Start, stop, restart workspaces and manage lifecycle modes
- [Logs](/docs/api/logs.md): Workspace log management and streaming
- [Metadata](/docs/api/metadata.md): Custom key-value metadata on workspaces
- [Metrics & Stats](/docs/api/metrics.md): Live stats, SSE streaming, and VM runtime info
- [Namespaces](/docs/api/namespaces.md): Organize workspaces, enforce resource limits, control quotas, and manage overdraft policies
- [Network](/docs/api/network.md): Firewall rules, ingress/egress, private links, and outbound IP management
- [Notifications](/docs/api/notifications.md): Push notifications from inside a workspace to the Oblien app
- [Pages](/docs/api/pages.md): Deploy and manage static pages served from the edge with optional custom domains
- [Public Access](/docs/api/public-access.md): Expose workspace ports to the internet with preview URLs
- [Resources](/docs/api/resources.md): Get and update workspace CPU, memory, and disk
- [Routes](/docs/api/routes.md): Per-deployment edge routing — attach an ordered rule table to any domain (static Page, VM, or compose) with proxy, rewrites, redirects, headers and SPA fallback; versioned, no redeploy
- [Runtime API Access](/docs/api/runtime-api-access.md): Enable the workspace internal server, manage tokens, and control access
- [Scoped Tokens](/docs/api/scoped-tokens.md): Issue short-lived JWTs scoped to a namespace or workspace for multi-tenant SaaS
- [Snapshots & Archives](/docs/api/snapshots.md): Save and restore workspace state
- [SSH](/docs/api/ssh.md): Connect with your account, transfer files and manage workspace SSH
- [Usage & Activity](/docs/api/usage.md): Usage history, credits chart, and resource tracking
- [Workloads](/docs/api/workloads.md): Managed background processes with lifecycle control
- [Workspaces](/docs/api/workspaces.md): Create, list, get, update, and delete workspaces

## concepts

- [Billing & Credits](/docs/concepts/billing.md): Current compute contracts, wallet funding and existing credit metering
- [PAYG and monthly compute](/docs/concepts/compute-billing.md): PAYG or prepaid monthly pools, included internet transfer, spending budgets and saved usage comparisons
- [Edge Proxy](/docs/concepts/edge-proxy.md): Route subdomains through the edge to verified external upstreams
- [Images](/docs/concepts/images.md): Understanding workspace images and choosing the right base
- [Plans & Limits](/docs/concepts/limits.md): Per-plan caps on tunnels, pages, edge proxies, custom domains, and monthly traffic
- [Modes](/docs/concepts/modes.md): Permanent vs temporary workspaces, TTL, and restart policies
- [Networking](/docs/concepts/networking.md): How workspace networking, firewalls, and public access work
- [Notifications](/docs/concepts/notifications.md): How agents inside a workspace push notifications to the Oblien app
- [Pages](/docs/concepts/pages.md): Deploy static files from workspaces to the edge — no running VM required
- [Resource Pools](/docs/concepts/resource-pools.md): How CPU, memory, and disk quotas work across your workspaces
- [Webhooks](/docs/concepts/webhooks.md): Receive real-time HTTP callbacks when events happen in your workspaces

## runtime-api

- [Command Execution](/docs/runtime-api/exec.md): Run commands and manage background tasks inside the workspace
- [Files](/docs/runtime-api/files.md): List, read, write, create, and delete files and directories inside the workspace
- [Overview](/docs/runtime-api.md): Direct API access to the workspace runtime - file operations, search, terminal, and command execution
- [Proxy](/docs/runtime-api/proxy.md): Reverse-proxy HTTP and WebSocket requests to loopback services inside the workspace
- [Search](/docs/runtime-api/search.md): Content search with ripgrep and filename search inside the workspace
- [Connection & Auth](/docs/runtime-api/server-setup.md): Enable the workspace internal server, understand the two connection methods, and configure access
- [Terminal](/docs/runtime-api/terminal.md): Create and manage interactive terminal sessions inside the workspace
- [File Watcher](/docs/runtime-api/watcher.md): Watch for file system changes in real time over WebSocket

## cli

- [API Access](/docs/cli/api-access.md): Manage Runtime API access and tokens for workspaces
- [Authentication](/docs/cli/authentication.md): Log in, log out, and manage auth status
- [Config](/docs/cli/config.md): Manage stored credentials and configuration
- [Domains](/docs/cli/domains.md): Connect and manage custom domains via CLI
- [Exec](/docs/cli/exec.md): Execute commands and manage tasks in workspace runtimes
- [Files](/docs/cli/files.md): Manage workspace files — list, read, write, delete, and stream
- [Images](/docs/cli/images.md): Browse available workspace images
- [CLI Overview](/docs/cli.md): The Oblien CLI — manage workspaces, namespaces, files, and more from the command line
- [Installation](/docs/cli/installation.md): Install the Oblien CLI
- [Lifecycle](/docs/cli/lifecycle.md): Manage workspace lifecycle mode — permanent, temporary, TTL, and destroy
- [Logs](/docs/cli/logs.md): View, stream, and manage workspace logs
- [Metadata](/docs/cli/metadata.md): Manage workspace key-value metadata tags
- [Metrics](/docs/cli/metrics.md): View workspace resource metrics and real-time stats
- [Namespaces](/docs/cli/namespaces.md): Manage namespaces — CRUD, lifecycle, quotas, usage, and activity
- [Network](/docs/cli/network.md): Configure workspace networking, public access, and outbound IPs
- [Public Access](/docs/cli/public-access.md): Expose and revoke public ports on workspaces
- [Search](/docs/cli/search.md): Search file contents and filenames inside workspaces
- [Skills](/docs/cli/skills.md): Install and manage agent skills for AI coding assistants
- [Snapshots](/docs/cli/snapshots.md): Create, restore, and manage workspace snapshots and archives
- [SSH](/docs/cli/ssh.md): Manage SSH access to workspaces
- [Terminal](/docs/cli/terminal.md): Manage runtime terminal sessions
- [Tunnel](/docs/cli/tunnel.md): Expose local ports through the Oblien edge
- [Usage](/docs/cli/usage.md): View workspace usage, credits, and tracking
- [Watcher](/docs/cli/watcher.md): Manage file system watchers in workspace runtimes
- [Workloads](/docs/cli/workloads.md): Manage workspace workloads — containers and processes
- [Workspaces](/docs/cli/workspaces.md): Create, list, start, stop, and manage workspaces

## mcp

- [Control Plane MCP](/docs/mcp/control-plane.md): 105 tools for managing Oblien workspaces — create, configure, monitor, and destroy from any MCP client
- [Overview](/docs/mcp.md): Model Context Protocol (MCP) servers for Oblien — manage workspaces and interact with their runtimes from any MCP-compatible client
- [Runtime MCP](/docs/mcp/runtime.md): 23 tools for interacting with a running workspace — files, search, exec, terminals, and file watchers over MCP

## skills

- [Agent Setup](/docs/skills/agents.md): How to use Oblien skills with Claude Code, Cursor, OpenClaw, and other AI agents
- [Skill Catalog](/docs/skills/catalog.md): Browse and download all available Oblien skills for AI agents
- [Skill Format](/docs/skills/format.md): The AgentSkills standard and SKILL.md structure used by Oblien skills
- [Overview](/docs/skills.md): Agent-readable skill packages that teach AI coding agents how to use the Oblien platform
- [Installing Skills](/docs/skills/installing.md): Install Oblien skills via npx, manual download, or agent-specific tools

## cdn

- [Custom domains](/docs/cdn/custom-domains.md): Serve your CDN assets from your own domain (cdn.yourbrand.com) via the /cdn/domains API — DNS verification + automatic TLS.
- [CDN](/docs/cdn.md): Store and deliver images, videos, documents and archives using your Oblien credit wallet.
- [How it works](/docs/cdn/overview.md): One upload operation, one credit wallet, and optional namespace isolation.
- [Namespace quotas](/docs/cdn/quotas.md): Share one account allowance while isolating each tenant's files, storage and CDN credit budget.
- [Files and usage](/docs/cdn/stats.md): Inspect authoritative files, quota reservations, credit spending and origin delivery.
- [Storage and delivery](/docs/cdn/storage.md): Destination selection, stable file URLs and direct edge delivery from local or private object storage.
- [Storage, traffic and credits](/docs/cdn/traffic.md): CDN media uses your existing credit wallet, with metered storage and origin delivery.
- [Expiry, trash and deletion](/docs/cdn/ttl.md): Durable file expiry and node-confirmed deletion keep storage and credits consistent.
- [Uploads and variants](/docs/cdn/uploads.md): Resumable media uploads, image transformations and raw or compressed video storage.