codespace

A runnable Go backend MVP skeleton that manages local workspaces, file operations through an abstract filesystem, and OpenCode processes.

V1 scope

• Workspace creation, lookup, and deletion backed by local directories.
• File read/write/list/mkdir/remove/rename/stat through a FileSystem interface with path-escape protection.
• OpenCode process start/stop/restart/status per workspace.
• HTTP API using Gin for routing with JSON responses.
• Explicit http.Server composition with configurable timeouts and max header bytes.

Not implemented in v1

Docker, authentication, Git integration, LSP, AI Agent orchestration, web frontend, and full watcher/WebSocket event streaming are out of scope for the first version.

Run

make run

The server listens on :8080 by default. Override via configs/config.yaml or environment variables:

Variable	Description
CODESPACE_ADDR	Listen address
CODESPACE_WORKSPACE_ROOT	Workspace root directory
CODESPACE_OPENCODE_COMMAND	OpenCode binary path
CODESPACE_READ_TIMEOUT	HTTP read timeout (e.g. 15s)
CODESPACE_WRITE_TIMEOUT	HTTP write timeout (e.g. 15s)
CODESPACE_IDLE_TIMEOUT	HTTP idle timeout (e.g. 60s)
CODESPACE_MAX_HEADER_BYTES	Max header bytes (e.g. 1048576)
CODESPACE_LOG_LEVEL	Log level (debug, info, warn, error)
CODESPACE_LOG_FORMAT	Log format (json, text)

Test

make test

Configuration

configs/config.yaml:

server:
  addr: ":8080"
  readTimeout: "15s"
  writeTimeout: "15s"
  idleTimeout: "60s"
  maxHeaderBytes: 1048576
workspace:
  root: "./workspaces"
process:
  opencodeCommand: "opencode"
log:
  level: "info"
  format: "json"

The server is started through an explicit http.Server{Handler: router} — it does not use gin.Engine.Run().

Logging

codespace uses the Go standard library log/slog for application logs. Default output is JSON to stdout.

log:
  level: "info"
  format: "json"

Environment overrides:

• CODESPACE_LOG_LEVEL (debug, info, warn, error)
• CODESPACE_LOG_FORMAT (json, text)

All application logs must go through log/slog. Do not use fmt.Print*, log.Printf, gin.Logger(), or third-party logging libraries in server runtime code.

API examples

Health check:

curl -s http://localhost:8080/healthz

Create a workspace:

curl -s -X POST http://localhost:8080/api/workspaces \
  -H 'Content-Type: application/json' \
  -d '{"id":"user1"}'

Write a file:

curl -s -X PUT http://localhost:8080/api/workspaces/user1/files/write \
  -H 'Content-Type: application/json' \
  -d '{"path":"main.go","content":"package main\n"}'

Read a file:

curl -s 'http://localhost:8080/api/workspaces/user1/files/read?path=main.go'