Build a legible
development environment.

Overview

Code OS is an operational command center for local or remote development machines. It discovers projects and Git worktrees, observes Portly applications and coding agents, indexes screenshots, and serves the result through one authenticated dashboard.

Installation

Linux amd64

mkdir -p ~/.local/bin
curl -L https://github.com/Melvynx/code-os/releases/latest/download/code-os-linux-amd64 -o ~/.local/bin/code-os
chmod +x ~/.local/bin/code-os
code-os version

Build from source

git clone https://github.com/Melvynx/code-os.git
cd code-os
corepack pnpm --dir internal/dashboard install --frozen-lockfile
corepack pnpm --dir internal/dashboard build
go build -o code-os ./cmd/code-os

Setup

The guided flow asks where projects and screenshots live, how Portly is configured, where the dashboard stores its credentials, and which Cloudflare and skills-sync settings belong to this machine.

code-os setup
code-os doctor
code-os service install

On Linux, service install starts Code OS immediately, enables it after every reboot, and installs the skills-sync timer when a repository is configured. Use code-os dashboard only for an interactive foreground run.

Generate dedicated secrets instead of reusing a personal password:

openssl rand -base64 32 > dashboard-password
openssl rand -hex 32 > media-bypass-key
openssl rand -hex 32 > session-key
chmod 600 dashboard-password media-bypass-key session-key

Commands

Command center

Opening the Code OS hostname routes directly to /app/. A signed-in or explicitly trusted connection sees the live dashboard; every other connection receives the HTML sign-in form. Public product documentation remains available at /docs.

The dashboard brings projects, every Git worktree, application state, Git changes, grouped screenshot evidence, and machine settings into one operational view. Settings can change project roots, Cloudflare fields, skills repository details, and credential-file locations. Secret values are write-only.

Projects and worktrees

Each configured root is scanned for repositories and nested applications. Code OS calls git worktree list --porcelain for every repository, so linked checkouts are first-class projects rather than invisible copies.

The dashboard shows their branch, path, ahead/behind state, and modified, added, deleted, untracked, or conflicted file counts.

Applications and coding agents

Portly remains the source of truth for persistent applications and duplicate prevention. The Applications page keeps the complete Portly inventory visible, including stopped and failed entries, and adds a live resource view for currently running processes.

CPU and resident memory are shown for each running Portly app and for grouped Codex, Cursor, Claude, OpenCode, Aider, and Gemini process trees. Wrapped agents are detected by safe executable signatures without returning their complete command arguments to the browser.

Stopping a process

• Application controls call Portly with the exact currently running application ID.
• Agent controls send SIGTERM to an identifier containing both PID and kernel start time, which prevents PID-reuse mistakes.
• Every action requires a confirmation and an authenticated same-origin POST.
• Code OS refuses to terminate the process tree hosting the command center itself.

Screenshots and evidence

Visual artifacts are grouped by feature directory and ordered by recency. The authenticated gallery provides a human view; an optional media bypass URL lets Cursor or Codex render a specific image directly.

https://your-code-os.example/media/SCREENSHOT_ID?bp=YOUR_MEDIA_KEY

https://your-code-os.example/files/FEATURE/EVIDENCE.png?bp=YOUR_MEDIA_KEY

Cloudflare Tunnel

Keep Code OS bound to 127.0.0.1, then route the main hostname and each portNNNN hostname to Code OS through Cloudflare Tunnel. The gateway requires the Code OS session before proxying a healthy Portly application.

code-os dashboard
# Tunnel origin example
http://127.0.0.1:7890

Start automatically on Linux

code-os service install writes a hardened systemd user service for the current binary, enables user lingering, reloads systemd, enables the unit, and restarts it immediately. The daemon therefore returns after a VPS reboot without requiring an SSH login.

code-os service install
code-os doctor
systemctl --user status code-os.service --no-pager
loginctl show-user "$USER" -p Linger

Running the install command again updates the unit to the current binary and safely restarts the service. If skills synchronization is configured, the same command installs and enables its two-minute timer.

Security model

• The dashboard listens on loopback by default.
• Credentials are read from permission-restricted files, not committed config.
• Successful sign-in creates an HTTP-only session cookie.
• A stable 256-bit signing key keeps sessions valid across safe restarts.
• After signing in, Settings shows the detected exact IP and a Trust this IP button. The same control can revoke it immediately.
• The JSON API requires a valid session or an IP that you explicitly trusted after signing in.
• The media bypass is separately generated and scoped to image reads.
• Cloudflare provides the public TLS boundary.

Configuration

The exact file is generated by code-os setup and can be updated from /app/settings. Token values are write-only and never returned by the API. Configuration changes require a service restart; trusting or revoking the current IP applies immediately.

{
  "version": 1,
  "environmentName": "dev-vps",
  "environmentType": "remote",
  "address": "127.0.0.1:7890",
  "projectsRoots": ["/root/projects"],
  "screenshotsRoot": "/root/screenshots",
  "filesRoot": "/root/.local/share/code-os/files",
  "dataDir": "/root/.local/share/code-os",
  "portlyBinary": "portly",
  "auth": {
    "username": "code-os",
    "passwordFile": "/root/.config/code-os/dashboard-password",
    "bypassKeyFile": "/root/.config/code-os/media-bypass-key",
    "sessionKeyFile": "/root/.config/code-os/session-key",
    "trustedIPsFile": "/root/.config/code-os/trusted-ips"
  },
  "skills": {
    "repository": "[email protected]:YOUR_ACCOUNT/agents-config.git",
    "directory": "/root/.agents",
    "branch": "main"
  }
}

Need implementation details? Read the project README .