OpenCode Web Server

A containerized web server that runs OpenCode commands via HTTP POST requests, with optional GitHub repository integration.

Features

• HTTP API: POST requests to /run endpoint
• Authentication: API key support via headers
• Configurable timeouts: Max execution time limits
• Request size limits: Prevent abuse
• Health checks: Built-in health endpoint
• Structured logging: Request IDs and execution times
• Graceful shutdown: Proper signal handling
• Repository integration: Clone and work with GitHub repositories

Quick Start

1. Build the Docker image

docker build -t opencode-server .

2. Run the container

docker run -d \
  -p 8080:8080 \
  -e OPENCODE_AUTH_TOKEN="your-opencode-token" \
  -e OPENCODE_AUTH_JSON='{"anthropic":{"type":"oauth","refresh":"your-refresh-token","access":"your-access-token","expires":1755523718697}}' \
  -e OPENCODE_CONFIG_JSON='{"theme":"dark","editor":"vscode","debug":true}' \
  -e API_KEY="your-api-key" \
  --name opencode-server \
  opencode-server

3. Send requests

# Health check
curl http://localhost:8080/health

# Execute opencode (with authentication)
curl -X POST \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: text/plain" \
  -d "Create a simple hello world function in Python" \
  http://localhost:8080/run

OpenCode Authentication

OpenCode supports multiple AI providers (Anthropic, OpenAI, etc.) through provider-specific authentication. You can configure authentication in two ways:

1. OPENCODE_AUTH_TOKEN: Simple token-based authentication (required for basic operation)
2. OPENCODE_AUTH_JSON: JSON-based configuration for advanced provider authentication

OpenCode Configuration

You can also provide general configuration settings using:

3. OPENCODE_CONFIG_JSON: JSON-based configuration for OpenCode settings

Provider Authentication (OPENCODE_AUTH_JSON)

For advanced provider authentication, you can pass a JSON string via the OPENCODE_AUTH_JSON environment variable. This JSON should contain authentication details for each provider you want to use.

Example JSON structure:

{
  "anthropic": {
    "type": "oauth",
    "refresh": "sk-ant-ort01-_Cnd2_OMeh9FPAqzJlF1zAEbq9QwKDSBPvP4hBfqDmh9WJqYGUx67UjlGDTIRGwvZ7AKMw-pLMedAAA",
    "access": "sk-ant-oat01-CnT57i25S62G19BDWwItiROtH-yL0JObzu6WUgg67pblNrwQ9TlelOy-G9Ag-iyaD2AAA",
    "expires": 1755523718697
  }
}

This JSON will be written to /root/.local/share/opencode/auth.json inside the container, which OpenCode will automatically use for provider authentication.

Configuration Settings (OPENCODE_CONFIG_JSON)

For general OpenCode configuration, you can pass a JSON string via the OPENCODE_CONFIG_JSON environment variable. This JSON can contain various OpenCode settings and preferences.

Example JSON structure:

{
  "theme": "dark",
  "editor": "vscode", 
  "debug": true,
  "timeout": 300
}

This JSON will be written to /root/.config/opencode/config.json inside the container, which OpenCode will automatically use for configuration.

Environment Variables

Variable	Required	Default	Description
OPENCODE_AUTH_TOKEN	✅	-	Your OpenCode authentication token
OPENCODE_AUTH_JSON	❌	-	JSON string containing OpenCode provider authentication (anthropic, openai, etc.)
OPENCODE_CONFIG_JSON	❌	-	JSON string containing OpenCode configuration settings
API_KEY	❌	-	Server API key for authentication
PORT	❌	8080	HTTP server port
MAX_EXECUTION_TIME	❌	300s	Maximum execution time for opencode commands
MAX_REQUEST_SIZE	❌	10485760	Maximum request body size in bytes (10MB)

API Endpoints

POST /run

Execute an opencode command with the request body as input.

Authentication: Optional (if API_KEY is set)

• Header: Authorization: Bearer <api-key>
• Header: Authorization: Api-Key <api-key>
• Header: X-API-Key: <api-key>

Request Body: Plain text or JSON containing the opencode prompt

For repository integration, use JSON format with the following fields:

• prompt: The opencode prompt (required)
• repository: The Git repository URL to clone and work with (optional)
• branch: The branch to work on (optional, defaults to main)

Response:

{
  "success": true,
  "output": "opencode execution output...",
  "error": null,
  "execution_time": "2.5s", 
  "request_id": "uuid",
  "branch": "branch-name", 
  "commit": "commit-hash"
}

When using repository integration, the response will additionally include:

• branch: The name of the branch created by opencode
• commit: The latest commit hash after execution

Status Codes:

• 200: Success
• 400: Bad request (empty body, invalid input)
• 401: Unauthorized (invalid/missing API key)
• 413: Request too large
• 408: Execution timeout
• 500: Internal server error

GET /health

Health check endpoint.

Response:

{
  "status": "healthy",
  "timestamp": "2024-01-01T12:00:00Z",
  "version": "1.0.0"
}

Examples

Repository Integration Examples

With repository (plain text)

curl -X POST \
  -H "Authorization: Bearer your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Add a README.md file", "repository": "https://github.com/username/repo.git"}' \
  http://localhost:8080/run

With repository and branch (JSON)

curl -X POST \
  -H "X-API-Key: your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Fix bug in main.go", "repository": "https://github.com/username/repo.git", "branch": "bugfix-branch"}' \
  http://localhost:8080/run

Basic usage (no auth)

curl -X POST \
  -H "Content-Type: text/plain" \
  -d "Write a function to calculate fibonacci numbers" \
  http://localhost:8080/run

With authentication

curl -X POST \
  -H "Authorization: Bearer your-secret-key" \
  -H "Content-Type: text/plain" \
  -d "Create a REST API endpoint for user management" \
  http://localhost:8080/run

JSON request

curl -X POST \
  -H "X-API-Key: your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Build a React component for a todo list"}' \
  http://localhost:8080/run

Docker Compose

version: '3.8'
services:
  opencode-server:
    build: .
    ports:
      - "8080:8080"
    environment:
      - OPENCODE_AUTH_TOKEN=${OPENCODE_AUTH_TOKEN}
      - OPENCODE_AUTH_JSON=${OPENCODE_AUTH_JSON}
      - OPENCODE_CONFIG_JSON=${OPENCODE_CONFIG_JSON}
      - API_KEY=${API_KEY}
      - MAX_EXECUTION_TIME=600s
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3

Production Deployment

Security Considerations

1. Always set an API_KEY in production
2. Use HTTPS with a reverse proxy (nginx, traefik, etc.)
3. Set appropriate request size limits
4. Configure execution timeouts based on your needs
5. Monitor logs for suspicious activity

Reverse Proxy Example (nginx)

server {
    listen 443 ssl;
    server_name your-domain.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # Increase timeouts for long-running opencode operations
        proxy_read_timeout 600s;
        proxy_send_timeout 600s;
    }
}

Monitoring

The server provides structured JSON logs with request IDs for correlation:

2024/01/01 12:00:00 [abc-123-def] POST /run from 192.168.1.100
2024/01/01 12:00:00 [abc-123-def] Executing opencode with 45 characters of input
2024/01/01 12:00:05 [abc-123-def] Execution completed successfully in 4.8s

Use tools like Prometheus, Grafana, or ELK stack to monitor:

• Request rates and response times
• Error rates and types
• Execution durations
• Resource usage

Troubleshooting

Common Issues

1. "OPENCODE_AUTH_TOKEN environment variable is required"

   • Ensure the token is set in your environment or Docker run command

2. "Authentication required"

   • Check your API_KEY header format
   • Verify the API_KEY environment variable

3. "Request too large"

   • Increase MAX_REQUEST_SIZE or reduce your request size

4. "Execution timeout"

   • Increase MAX_EXECUTION_TIME for longer operations

5. "Failed to clone repository"

   • Check your GITHUB_TOKEN for private repositories
   • Verify the repository URL is accessible

Debug Mode

Run with debug logging:

docker run -it --rm \
  -p 8080:8080 \
  -e OPENCODE_AUTH_TOKEN="your-token" \
  opencode-server