OpenCode Dashboard

A powerful remote dashboard for managing OpenCode AI instances on your servers. Monitor system resources, manage files, access terminals, and control OpenCode - all from a beautiful web interface.

┌─────────────────────┐                    ┌─────────────────────────────────┐
│   Your Computer     │                    │        Your Server              │
│                     │                    │                                 │
│  ┌───────────────┐  │      Internet      │  ┌───────────┐    ┌───────────┐ │
│  │   Dashboard   │──┼───────────────────▶│  │   Agent   │───▶│ OpenCode  │ │
│  │   (Browser)   │  │                    │  │  :4097    │    │  :4096    │ │
│  └───────────────┘  │                    │  └───────────┘    └───────────┘ │
└─────────────────────┘                    └─────────────────────────────────┘

Features

Feature	Description
File Browser	Browse, create, edit, rename, and delete files on your remote server with syntax highlighting
System Monitor	Real-time monitoring of CPU, RAM, disk usage, and system load with live charts
OpenCode Management	Install, start, stop, and restart OpenCode AI with one click
Web Terminal	Full-featured terminal access directly in your browser via WebSocket
Session History	View and search through OpenCode conversation history
Isolated Workspaces	Run code in secure systemd-nspawn containers for sandboxed execution
Multi-User Auth	Secure authentication with bcrypt password hashing and JWT tokens
Responsive Design	Works seamlessly on desktop, tablet, and mobile devices

Quick Start

Get up and running in under 5 minutes.

1. Install the Agent on Your Server

ssh user@your-server

curl -fsSL https://raw.githubusercontent.com/itsmylife44/opencode-dashboard/main/scripts/install-agent.sh | bash

The installer will:

Download the appropriate binary for your architecture
Create a dedicated opencode user (if running as root)
Set up a systemd service
Install workspace dependencies (systemd-nspawn, debootstrap)
Generate a secure authentication token

After installation, you'll see:

════════════════════════════════════════════════════════
   OpenCode Agent installed successfully!
════════════════════════════════════════════════════════

  Dashboard Connection Details:

  Agent URL:   http://203.0.113.50:4097
  Auth Token:  a7f3b2c1d4e5f6a7b8c9d0e1f2a3b4c5...

  Workspace Support:
  ✓ systemd-nspawn installed
  ✓ debootstrap installed
  ✓ Workspace directory: /home/opencode/.opencode-workspaces

  Save these credentials - you'll need them in the dashboard!

════════════════════════════════════════════════════════

Save the Auth Token - you'll need it to connect the dashboard.

2. Start the Dashboard

On your local machine:

git clone https://github.com/itsmylife44/opencode-dashboard.git
cd opencode-dashboard

bun install
bun run dev

3. Connect to Your Server

Open http://localhost:3000 in your browser
Select "Agent" mode in the setup wizard
Enter your server's Agent URL and Auth Token
Create your dashboard login credentials
Start managing your server!

Installation

Server Agent Installation

Automatic Installation (Recommended)

The install script supports running as root or as a regular user:

curl -fsSL https://raw.githubusercontent.com/itsmylife44/opencode-dashboard/main/scripts/install-agent.sh | bash

When running as root, you'll be prompted to:

Create a new opencode user (recommended)
Use an existing user
Run as root (not recommended)

Supported Operating Systems:

OS	Architectures	Package Manager
Ubuntu 20.04+	amd64, arm64	apt
Debian 11+	amd64, arm64	apt
Fedora 36+	amd64, arm64	dnf
CentOS/RHEL 8+	amd64, arm64	yum
Arch Linux	amd64, arm64	pacman
Alpine Linux	amd64, arm64	apk

Environment Variables:

Variable	Default	Description
`AGENT_PORT`	`4097`	Port the agent listens on
`AGENT_TOKEN`	auto-generated	Authentication token
`AGENT_USER`	interactive	User to run the agent as
`INSTALL_DIR`	`~/.local/bin`	Binary installation directory
`SKIP_SYSTEMD`	`false`	Skip systemd service setup
`SKIP_WORKSPACES`	`false`	Skip workspace dependency installation

Example with custom settings:

AGENT_PORT=8080 SKIP_WORKSPACES=true curl -fsSL https://raw.githubusercontent.com/itsmylife44/opencode-dashboard/main/scripts/install-agent.sh | bash

Manual Installation

Download the binary directly:

# AMD64 (Intel/AMD processors)
curl -fsSL https://github.com/itsmylife44/opencode-dashboard/releases/latest/download/opencode-agent-linux-amd64 -o opencode-agent

# ARM64 (Raspberry Pi, Apple Silicon VMs, AWS Graviton)
curl -fsSL https://github.com/itsmylife44/opencode-dashboard/releases/latest/download/opencode-agent-linux-arm64 -o opencode-agent

chmod +x opencode-agent

Verify the download:

curl -fsSL https://github.com/itsmylife44/opencode-dashboard/releases/latest/download/opencode-agent-linux-amd64.sha256 | sha256sum -c

Run the agent:

export AGENT_TOKEN=$(openssl rand -hex 32)
echo "Your token: $AGENT_TOKEN"
./opencode-agent

Dashboard Setup

Prerequisites:

Node.js 20+ or Bun (recommended)
Modern web browser (Chrome, Firefox, Safari, Edge)

Installation:

git clone https://github.com/itsmylife44/opencode-dashboard.git
cd opencode-dashboard

# Using Bun (recommended)
bun install
bun run dev

# Or using npm
npm install
npm run dev

The dashboard will be available at http://localhost:3000.

Production Build:

bun run build
bun run start

Configuration

Dashboard Configuration

Dashboard settings are stored in ~/.opencode-dashboard/:

File	Purpose
`credentials.json`	Encrypted user credentials (bcrypt)
`settings.json`	Connection settings and preferences
`.setup.lock`	Setup completion flag

Agent Configuration

The agent is configured via environment variables:

Variable	Default	Description
`AGENT_PORT`	`4097`	HTTP server port
`AGENT_TOKEN`	required	Authentication token (64-char hex)
`AGENT_HOME_ONLY`	`true`	Restrict file access to user's home directory
`WORKSPACE_PATH`	`~/.opencode-workspaces`	Directory for isolated workspaces
`OPENCODE_SERVER_URL`	`http://localhost:4096`	OpenCode API endpoint

Firewall Configuration

Ensure port 4097 (or your custom port) is accessible:

# Ubuntu/Debian (UFW)
sudo ufw allow 4097/tcp

# CentOS/RHEL (firewalld)
sudo firewall-cmd --permanent --add-port=4097/tcp
sudo firewall-cmd --reload

# iptables
sudo iptables -A INPUT -p tcp --dport 4097 -j ACCEPT

Architecture

System Overview

┌──────────────────────────────────────────────────────────────────┐
│                        Your Computer                              │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │                    Next.js Dashboard                        │  │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │  │
│  │  │   File   │  │  System  │  │ Terminal │  │ OpenCode │   │  │
│  │  │ Browser  │  │ Monitor  │  │  (xterm) │  │ Manager  │   │  │
│  │  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘   │  │
│  │       │              │              │              │        │  │
│  │       └──────────────┴──────────────┴──────────────┘        │  │
│  │                           │                                  │  │
│  │                    API Routes / Proxy                        │  │
│  └───────────────────────────┼──────────────────────────────────┘  │
└──────────────────────────────┼──────────────────────────────────────┘
                               │ HTTPS/WSS
                               ▼
┌──────────────────────────────────────────────────────────────────┐
│                        Your Server                                │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │                    Go Agent (:4097)                         │  │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │  │
│  │  │  Files   │  │ Metrics  │  │   PTY    │  │ Service  │   │  │
│  │  │  API     │  │Collector │  │ Handler  │  │ Manager  │   │  │
│  │  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘   │  │
│  │       │              │              │              │        │  │
│  │       ▼              ▼              ▼              ▼        │  │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │  │
│  │  │Filesystem│  │  /proc   │  │  bash    │  │ systemd  │   │  │
│  │  └──────────┘  └──────────┘  └──────────┘  └──────────┘   │  │
│  └────────────────────────────────────────────────────────────┘  │
│                                                                   │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │                  OpenCode AI (:4096)                        │  │
│  └────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────┘

Project Structure

opencode-dashboard/
├── src/                          # Next.js Dashboard
│   ├── app/                      # App Router pages
│   │   ├── (auth)/              # Authentication pages
│   │   ├── (dashboard)/         # Protected dashboard pages
│   │   └── api/                 # API routes (proxy to agent)
│   ├── components/              # React components
│   │   ├── file-browser/        # File management UI
│   │   ├── monitoring/          # System metrics charts
│   │   ├── opencode/            # OpenCode management
│   │   ├── setup/               # Setup wizard
│   │   └── terminal/            # xterm.js terminal
│   ├── lib/                     # Utilities and clients
│   │   ├── agent/               # Agent API client
│   │   ├── auth/                # Authentication logic
│   │   └── opencode/            # OpenCode SDK integration
│   └── hooks/                   # Custom React hooks
├── opencode-agent/              # Go Agent
│   ├── cmd/agent/               # Entry point
│   └── internal/                # Internal packages
│       ├── api/                 # HTTP handlers
│       ├── config/              # Configuration
│       ├── files/               # File operations
│       ├── metrics/             # System metrics collector
│       ├── terminal/            # PTY/WebSocket handler
│       └── workspace/           # Container management
├── scripts/                     # Installation scripts
│   └── install-agent.sh         # Production installer
└── .github/workflows/           # CI/CD pipelines
    └── agent-release.yml        # Auto-build on release

API Reference

Authentication

All API requests require the Authorization header:

Authorization: Bearer <your-token>

Endpoints

Health Check

GET /api/health

Returns agent status and version information.

System Metrics

GET /api/metrics

Returns CPU, memory, disk usage, and system load.

Response:

{
  "cpu": {
    "usage": 23.5,
    "cores": 8
  },
  "memory": {
    "total": 16777216000,
    "used": 8388608000,
    "percent": 50.0
  },
  "disk": {
    "total": 500000000000,
    "used": 250000000000,
    "percent": 50.0
  },
  "load": {
    "load1": 1.5,
    "load5": 1.2,
    "load15": 1.0
  }
}

File Operations

GET /api/files?path=/home/user
GET /api/files/content?path=/home/user/file.txt
POST /api/files/write
POST /api/files/delete
POST /api/files/rename
POST /api/files/mkdir

Service Management

GET /api/service/status
POST /api/service/start
POST /api/service/stop
POST /api/service/restart

Terminal

WebSocket /api/terminal/ws

Full PTY terminal access via WebSocket connection.

Security

Authentication & Authorization

Token-based authentication: 256-bit cryptographically secure tokens
bcrypt password hashing: 12 rounds for dashboard login
JWT session tokens: Secure, httpOnly cookies
CORS protection: Configurable origin restrictions

File System Security

Path traversal protection: All paths validated against home directory
Sensitive directory blocking: .ssh, .gnupg, .aws, .config/gcloud blocked by default
Symlink resolution: Prevents escape via symbolic links

Network Security

TLS recommended: Use a reverse proxy (nginx, Caddy) with HTTPS in production
Rate limiting: Built-in protection against brute force attacks
Request validation: All inputs sanitized and validated

Container Isolation

Workspaces use systemd-nspawn for secure isolation:

Separate filesystem namespace
Network isolation options
Resource limits (CPU, memory)
Capability dropping

Development

Prerequisites

Go 1.21+ (for agent)
Node.js 20+ or Bun (for dashboard)
Make (for build scripts)

Setup Development Environment

# Clone the repository
git clone https://github.com/itsmylife44/opencode-dashboard.git
cd opencode-dashboard

# Install dashboard dependencies
bun install

# Build the agent
cd opencode-agent
make build
cd ..

# Start both in development mode
./dev.sh

Running Tests

# Dashboard tests
bun run test

# Agent tests
cd opencode-agent
go test ./...

Building for Production

# Build dashboard
bun run build

# Build agent binaries
cd opencode-agent
make build-linux-amd64
make build-linux-arm64

Code Style

TypeScript: ESLint + Prettier
Go: gofmt + golint
Commits: Conventional Commits format

Troubleshooting

Agent Issues

Agent won't start:

# Check logs
sudo journalctl -u opencode-agent -f

# Verify token is set
cat ~/.config/opencode-agent/token

# Check port availability
sudo lsof -i :4097

Connection refused:

# Check if agent is running
sudo systemctl status opencode-agent

# Check firewall
sudo ufw status
sudo iptables -L -n | grep 4097

Dashboard Issues

Can't connect to agent:

Verify the agent URL is correct (include http://)
Check the auth token matches
Ensure port 4097 is open on the server
Try curl http://your-server:4097/api/health to test connectivity

Authentication failed:

# Reset dashboard credentials
rm ~/.opencode-dashboard/credentials.json
rm ~/.opencode-dashboard/.setup.lock
# Restart dashboard and re-run setup

Workspace Issues

Workspace commands fail:

# Check dependencies
which systemd-nspawn debootstrap

# Install missing dependencies
sudo apt install systemd-container debootstrap  # Ubuntu/Debian
sudo dnf install systemd-container debootstrap  # Fedora
sudo pacman -S systemd debootstrap              # Arch

# Check workspace directory permissions
ls -la ~/.opencode-workspaces

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'feat: add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

OpenCode AI - The AI coding assistant this dashboard manages
Next.js - React framework for the dashboard
Chi Router - Lightweight Go HTTP router
xterm.js - Terminal emulator for the web

Name		Name	Last commit message	Last commit date
Latest commit History 10 Commits
.github/workflows		.github/workflows
opencode-agent		opencode-agent
scripts		scripts
src		src
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
bun.lock		bun.lock
dev.sh		dev.sh
jest.api-setup.js		jest.api-setup.js
jest.config.js		jest.config.js
jest.setup.js		jest.setup.js
next-env.d.ts		next-env.d.ts
next.config.mjs		next.config.mjs
package.json		package.json
postcss.config.mjs		postcss.config.mjs
tsconfig.json		tsconfig.json

itsmylife44/opencode-dashboard

Folders and files

Latest commit

History

Repository files navigation