# OpenCode Sandbox
## Product Requirements Document (PRD)

**Version:** 1.0  
**Date:** March 1, 2026  
**Author:** Rakis (via ribby)  
**Status:** Draft

---

## Executive Summary

OpenCode Sandbox provides users with an isolated, ephemeral development environment accessible via a web-based terminal. Users can run OpenCode (an AI coding agent) and build applications without installing anything locally.

---

## Problem Statement

Developers and non-technical users want to:
1. **Use AI coding agents** without installing CLI tools locally
2. **Build and deploy applications** from any device (including mobile)
3. **Experiment safely** without affecting their local environment
4. **Access from anywhere** — browser-based, no setup required

Current solutions require:
- Local installation of Node.js, npm, CLI tools
- Technical knowledge to configure environments
- Risk of breaking local development setups

---

## Goals

### Primary Goals
1. Provide instant access to a Linux terminal with OpenCode pre-installed
2. Enable users to build, run, and deploy Permaweb apps from a browser
3. Support mobile users with a touch-friendly terminal interface

### Secondary Goals
1. Zero infrastructure for end users (no local setup)
2. Secure isolation (one sandbox per user)
3. Persistent workspaces (save/resume sessions)
4. Integration with Permaweb deployment (Arweave, AO, ArNS)

### Non-Goals
1. Full IDE (just terminal, not VS Code replacement)
2. Multi-player collaboration (single-user per sandbox)
3. Long-running servers (ephemeral workspaces)

---

## Target Users

| User Type | Description | Use Case |
|------------|-------------|----------|
| **Mobile Developer** | Wants to code from phone/tablet | Quick fixes, run OpenCode, deploy changes |
| **Non-technical Builder** | No dev environment installed | Build apps using natural language via OpenCode |
| **Permaweb Developer** | Building on Arweave | Test and deploy Permaweb apps |
| **Educator/Student** | Learning to code | Safe environment to experiment |
| **AI Agent Operator** | Running coding agents | Host agents in isolated environment |

---

## Features

### MVP Features (Phase 1)

| Feature | Priority | Description |
|---------|----------|-------------|
| Browser Terminal | P0 | xterm.js terminal in browser |
| Sandbox Creation | P0 | Spawn Vercel Sandbox on demand |
| OpenCode Pre-installed | P0 | `npm install -g opencode` in sandbox |
| Real-time I/O | P0 | WebSocket streaming terminal output |
| Auto-cleanup | P0 | Destroy sandbox after inactivity (30 min) |
| Status Indicator | P1 | Show connected/disconnected/creating states |

### Future Features (Phase 2+)

| Feature | Priority | Description |
|---------|----------|-------------|
| Preview URL | P1 | Expose port 3000 for live app preview |
| Session Persistence | P2 | Snapshot workspace, resume later |
| Permaweb Deploy | P2 | One-click deploy to Arweave |
| WorkOS Auth | P2 | User accounts, workspace history |
| Mobile Gestures | P2 | Pinch zoom, swipe keyboard |
| Saved Workspaces | P3 | Name and restore previous sessions |

---

## Technical Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                    BROWSER (Frontend)                       │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  React App                                          │   │
│  │  ┌─────────────┐  ┌─────────────────────────────┐  │   │
│  │  │  Terminal   │  │  Start Button / Status      │  │   │
│  │  │  (xterm.js) │  │  • Creating Sandbox...     │  │   │
│  │  │             │  │  • Connected               │  │   │
│  │  │  $ opencode │  │  • Disconnected            │  │   │
│  │  │  $ npm run  │  │                            │  │   │
│  │  └─────────────┘  └─────────────────────────────┘  │   │
│  └─────────────────────────────────────────────────────┘   │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           │ WebSocket (ws://host/ws/terminal/:id)
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                    BACKEND API (Hono)                        │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │  REST API    │  │  WebSocket   │  │  Sandbox     │      │
│  │              │  │  Handler      │  │  Manager     │      │
│  │  POST /api/  │  │              │  │              │      │
│  │  sandbox     │  │  stdin/stdout│  │  create()    │      │
│  │  GET /api/   │  │  ↔           │  │  destroy()   │      │
│  │  sandbox/:id │  │  terminal.js  │  │  getShell()  │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           │ Vercel Sandbox SDK
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                VERCEL SANDBOX (Per User)                    │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  Linux MicroVM (Node.js 24)                         │   │
│  │                                                     │   │
│  │  📦 OpenCode CLI                                    │   │
│  │  📦 Node.js + npm                                   │   │
│  │  📦 Git                                             │   │
│  │  📦 Vite, Arweave CLI (future)                      │   │
│  │                                                     │   │
│  │  📁 /workspace/                                     │   │
│  │     └── (user files)                                │   │
│  │                                                     │   │
│  │  🌐 Port 3000 (dev server preview)                  │   │
│  │  ⏱️  30-minute timeout                               │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                           │
                           │ (Future: Deploy to Arweave)
                           │
                           ▼
              ┌───────────────────────┐
              │      PERMAWEB         │
              │  Arweave / AO / ArNS  │
              └───────────────────────┘
```

---

## API Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/sandbox` | Create new sandbox |
| GET | `/api/sandbox/:id` | Get sandbox status |
| DELETE | `/api/sandbox/:id` | Destroy sandbox |
| GET | `/api/sandboxes` | List all user sandboxes |
| WS | `/ws/terminal/:id` | Terminal I/O stream |

---

## WebSocket Protocol

### Client → Server
```json
{ "type": "input", "data": "ls -la\n" }
```

### Server → Client
```json
{ "type": "output", "data": "total 0\ndrwxr-xr-x 2 user user 4096 Mar  1 12:00 .\n" }
{ "type": "status", "data": "ready" }
{ "type": "error", "data": "Sandbox not found" }
```

---

## User Journey

### First-Time User
1. Opens app in browser
2. Sees "Start Sandbox" button
3. Clicks button → "Creating sandbox..." → "Installing OpenCode..."
4. Terminal appears with `$` prompt
5. Types `opencode --help`
6. Sees OpenCode help output
7. Builds first app

### Returning User (Phase 2)
1. Opens app in browser
2. Sees previous workspace (if within 30 min)
3. Or prompts to restore from snapshot
4. Continues where left off

---

## Milestones

### Phase 1: MVP (2-3 days)
- [ ] Mock terminal UI (works without backend)
- [ ] Sandbox creation endpoint
- [ ] WebSocket terminal streaming
- [ ] OpenCode installation in sandbox
- [ ] Basic error handling
- [ ] Deploy to Hyper (onhyper.io)

### Phase 2: Persistence (1-2 days)
- [ ] Snapshot / hibernate inactive workspaces
- [ ] Restore from snapshot
- [ ] Session history in local storage

### Phase 3: Auth + Accounts (2-3 days)
- [ ] WorkOS AuthKit integration
- [ ] Per-user workspace mapping
- [ ] Workspace listing
- [ ] Account settings

### Phase 4: Permaweb Integration (2-3 days)
- [ ] Arweave wallet in sandbox
- [ ] Deploy to Arweave command
- [ ] ArNS domain registration
- [ ] Preview URL for deployed apps

---

## Success Metrics

| Metric | Target |
|--------|--------|
| Time to first terminal prompt | < 60 seconds |
| Terminal latency (input → output) | < 100ms |
| Sandbox creation success rate | > 95% |
| User retention (7-day) | > 30% |
| Mobile usage | > 40% of sessions |

---

## Risks & Mitigations

| Risk | Mitigation |
|------|------------|
| Vercel Sandbox availability | Fallback to mock mode; error UI |
| WebSocket connection drops | Auto-reconnect with status indicator |
| OpenCode install fails | Retry logic; clear error message |
| Cost overrun (sandbox time) | Hard timeout; snapshot early |
| Mobile keyboard issues | External keyboard support; touch commands |

---

## Technical Decisions

### Why Vercel Sandbox?
- Isolated Linux VMs per user
- No infrastructure management
- Fast startup (~10 seconds)
- WebSocket support for real-time I/O

### Why Hono?
- Lightweight serverless framework
- Native WebSocket support
- Works on Hyper, Vercel, Deno, Node

### Why xterm.js?
- Industry-standard terminal emulator
- Touch-friendly
- Fully styled/themable
- Mature ecosystem (VS Code uses it)

---

## Open Questions

1. **Cost model?** — Free tier? Usage-based?
2. **Session duration?** — 30 min default, extendable?
3. **File persistence?** — Snapshots vs. permanent storage?
4. **Multi-terminal?** — Multiple tabs/panes?
5. **Sharing?** — Collaborate with others?

---

## Appendix A: Command Reference

| Command | Description |
|---------|-------------|
| `opencode "create a blog"` | Run OpenCode with prompt |
| `opencode --help` | Show OpenCode help |
| `npm install <package>` | Install npm package |
| `npm run dev` | Start dev server |
| `git clone <url>` | Clone repository |
| `ls`, `cd`, `cat` | Standard Linux commands |

---

## Appendix B: Future Integrations

- **OpenClaw Skills** — Install Permaweb skills
- **AO Connect** — Run AO processes
- **ArNS** — Register permaweb domains
- **Hyper Deploy** — Deploy to Hyper directly
- **GitHub** — Push to repositories

---

**Document History**

| Version | Date | Author | Changes |
|---------|------|--------|---------|
| 1.0 | Mar 1, 2026 | ribby | Initial PRD |