Code Workspaces

​

Overview

• Ephemeral environments — Each workspace is an isolated Docker container
• Browser-based terminal — Full terminal emulation with xterm.js
• WebSocket connection — Real-time bidirectional communication
• Container lifecycle management — Automatic recovery and cleanup
• Session authentication — Secure access via JWT session tokens

​

Architecture

Chat Agent's start_coding tool
  ↓
createCodeWorkspaceContainer() (lib/tools/docker.js)
  ↓
Docker container runs claude-code-workspace image
  ↓
ttyd server on port 7681
  ↓
Browser navigates to /code/{id}
  ↓
TerminalView component (xterm.js)
  ↓
WebSocket connection
  ↓
ws-proxy.js authenticates and proxies
  ↓
ws://{containerName}:7681/ws

​

Data Flow

​

Container Creation

1. Chat agent calls start_coding tool
2. createCodeWorkspaceContainer() in lib/tools/docker.js creates a Docker container:
   • Image: claude-code-workspace
   • Entrypoint: ttyd bash
   • Port: 7681 (WebSocket)
   • Container name: code-workspace-{id}
3. Container registered in database with user ownership
4. Browser redirected to /code/{id}

​

Terminal Connection

1. Browser loads /code/{id} page
2. TerminalView component (xterm.js) initializes
3. Opens WebSocket to /api/code/ws/{id}
4. ws-proxy.js handles connection:
   • Authenticates session
   • Verifies workspace ownership
   • Proxies to container WebSocket
5. Bidirectional WebSocket proxying begins
6. User can type commands, agent can send output

​

Container Recovery

1. Inspects container via Docker Engine API (Unix socket)
2. Determines state: running, stopped, exited, paused, dead, missing
3. Takes action:
   • Running → Return success
   • Stopped/Exited/Paused → Restart container
   • Dead/Missing → Recreate container
4. Returns status: 'running', 'started', 'created', 'no_container', 'error'

​

WebSocket Authentication

​

Authentication Flow

1. Reads authjs.session-token cookie from HTTP upgrade request headers
2. Decodes JWT using next-auth/jwt decode() with AUTH_SECRET
3. Validates session and extracts user ID
4. Looks up workspace in database
5. Verifies workspace belongs to authenticated user
6. Rejects with:
   • 401 if no valid token
   • 403 if workspace not found or doesn’t belong to user
7. Proxies WebSocket bidirectionally to ws://{containerName}:7681/ws

​

Security Considerations

• Session tokens are httpOnly cookies (not accessible to JavaScript)
• Each workspace has a unique ID (UUID)
• Ownership verified on every connection
• WebSocket upgrade is atomic — no race conditions

​

Server Actions

​

Available Actions

import {
  getCodeWorkspaces,
  createCodeWorkspace,
  renameCodeWorkspace,
  starCodeWorkspace,
  deleteCodeWorkspace,
  ensureCodeWorkspaceContainer
} from 'thepopebot/code'

​

Action Details

const workspaces = await getCodeWorkspaces()
// [{ id, name, starred, created_at, user_id }]

const workspace = await createCodeWorkspace('My Project')
// { id: 'uuid', name: 'My Project', ... }

await renameCodeWorkspace(workspace.id, 'Updated Name')

await starCodeWorkspace(workspace.id, true)

await deleteCodeWorkspace(workspace.id)

const result = await ensureCodeWorkspaceContainer(workspace.id)
// { status: 'running' | 'started' | 'created' | 'no_container' | 'error' }

​

Container Lifecycle

​

Creation

import { createCodeWorkspaceContainer } from 'thepopebot/tools/docker'

const container = await createCodeWorkspaceContainer({
  id: 'uuid',
  name: 'My Workspace'
})

{
  Image: 'claude-code-workspace',
  name: `code-workspace-${id}`,
  ExposedPorts: { '7681/tcp': {} },
  HostConfig: {
    NetworkMode: 'bridge',
    AutoRemove: false
  },
  Cmd: ['bash']
}

​

States

​

Recovery

// In the page component
const { status } = await ensureCodeWorkspaceContainer(workspaceId)

if (status === 'error' || status === 'no_container') {
  // Show error message
} else {
  // Connect WebSocket
}

​

Cleanup

• User deletes the workspace (immediate)
• Container crashes and is recreated
• Docker daemon restarts (containers are not set to auto-restart)

​

Use Cases

​

Interactive Development

1. User: “Start a coding workspace for the new API endpoint”
2. Agent calls start_coding tool
3. Workspace created with full development environment
4. Agent can run commands, edit files, test code
5. User can type commands in the terminal
6. Changes saved to container filesystem

​

Debugging Sessions

1. User shares error message with agent
2. Agent creates workspace and reproduces the error
3. Agent runs debugger, inspects variables
4. Agent identifies root cause
5. Agent proposes fix and tests it in the workspace
6. User reviews and approves

​

Learning and Tutorials

1. User: “Teach me React hooks with live examples”
2. Agent creates workspace with React environment
3. Agent writes example code and runs it
4. User modifies examples in the terminal
5. Agent explains behavior and suggests improvements
6. User experiments with variations

​

Technical Details

​

Docker Image

• Node.js runtime
• Common development tools (git, curl, vim)
• ttyd (terminal WebSocket server)
• Bash shell

​

ttyd Server

ttyd --port 7681 bash

• Listens on port 7681
• Exposes WebSocket at /ws
• Streams bash terminal I/O

​

xterm.js Integration

import { Terminal } from 'xterm'
import { FitAddon } from 'xterm-addon-fit'

const terminal = new Terminal()
const fitAddon = new FitAddon()
terminal.loadAddon(fitAddon)
terminal.open(containerRef.current)
fitAddon.fit()

const ws = new WebSocket(`wss://example.com/api/code/ws/${id}`)
terminal.onData(data => ws.send(data))
ws.onmessage = e => terminal.write(e.data)

​

WebSocket Proxy

export const config = { api: { bodyParser: false } }

export default async function handler(req, res) {
  if (req.method !== 'GET') return res.status(405).end()
  
  const { id } = req.query
  const session = await validateSession(req)
  const workspace = await getWorkspace(id, session.userId)
  
  if (!workspace) return res.status(403).end()
  
  const wss = new WebSocketServer({ noServer: true })
  wss.handleUpgrade(req, req.socket, Buffer.alloc(0), ws => {
    const target = new WebSocket(`ws://code-workspace-${id}:7681/ws`)
    ws.on('message', data => target.send(data))
    target.on('message', data => ws.send(data))
  })
}

​

Troubleshooting

​

WebSocket Connection Failed

• Container not running
• Session expired
• Network connectivity issues

# Check container status
docker ps -a | grep code-workspace

# Restart container
docker restart code-workspace-{id}

# Check logs
docker logs code-workspace-{id}

​

Container Not Starting

• Docker daemon not running
• Image not pulled
• Resource constraints

# Pull image
docker pull claude-code-workspace

# Check Docker daemon
systemctl status docker

# Check resources
docker system df

​

Terminal Freezes

• Container process crashed
• WebSocket connection dropped
• Browser tab backgrounded (throttled)

• Refresh the page
• Check container logs
• Recreate the workspace

​

Best Practices

​

Limitations

• No persistence — Container filesystem is ephemeral. Use Git or volume mounts for persistence.
• No multi-user — One workspace per user session. Can’t share terminals between users.
• No clipboard integration — Copy/paste requires browser permissions and manual selection.
• No file upload — Use curl or git clone to get files into the container.
• Resource limits — Containers share host resources. Too many workspaces can exhaust memory.

​

Related Features

• Web Interface — Start coding workspaces from chat
• Docker Agent — Agent jobs can reference workspace code
• Skills — Skills can use code workspaces for testing