Skip to main content
Codeg’s standalone server mode lets you host your coding workspace on a remote Linux or macOS machine — a cloud VM, a development server, or a shared team instance — and access it from any browser. There is no GUI or desktop environment required. Common use cases
  • Remote development servers and cloud VMs
  • Shared team instances where multiple developers connect from their own browsers
  • Headless CI or automation environments

​
Install

Run the one-line installer. It detects your platform and architecture, downloads the latest binary and web assets, and installs them to /usr/local/bin by default.
curl -fsSL https://raw.githubusercontent.com/xintaofei/codeg/main/install.sh | bash
Install a specific version or to a custom directory:
curl -fsSL https://raw.githubusercontent.com/xintaofei/codeg/main/install.sh | bash -s -- --version v0.5.2 --dir ~/.local/bin
The installer requires sudo only if the target directory (default /usr/local/bin) is not writable by your user. Pass --dir ~/.local/bin to avoid sudo entirely.
Web assets are placed in /usr/local/share/codeg/web by default. The installer sets CODEG_STATIC_DIR accordingly in the printed quick-start command.

​
Start the server

1

Run codeg-server

After installation via the script, the binary is on your PATH:
codeg-server
If you installed manually or set a custom directory, prefix with the correct CODEG_STATIC_DIR:
CODEG_STATIC_DIR=/usr/local/share/codeg/web codeg-server
2

Note the auth token

On first start, Codeg prints a randomly generated token to stderr:
codeg-server listening on 0.0.0.0:3080
Auth token: a1b2c3d4e5f6...
Copy this token — you will need it to log in.To use a fixed token across restarts, set CODEG_TOKEN before starting the server:
CODEG_TOKEN=your-secret-token codeg-server
3

Open in your browser

Navigate to http://localhost:3080 (or the host and port you configured). Enter your token in the login prompt.

​
Authentication

Codeg uses token-based authentication. Every request to the server must include a valid token. Login prompt — Enter the token in the web UI when prompted. API requests — Pass the token as a Bearer header: 
curl -H "Authorization: Bearer your-secret-token" http://localhost:3080/api/...
WebSocket connections — Pass the token as a query parameter: 
ws://localhost:3080/ws?token=your-secret-token
Set CODEG_TOKEN to a fixed value in production. Without it, a new random token is generated each time the server restarts, which will log out active sessions.

​
Configuration

Configure Codeg with environment variables. All variables are optional; the defaults work for local use.
VariableDefaultDescription
CODEG_PORT3080HTTP port the server listens on
CODEG_HOST0.0.0.0Bind address
CODEG_TOKEN(random)Auth token — printed to stderr on start if not set
CODEG_DATA_DIR~/.local/share/codegDirectory for the SQLite database and settings
CODEG_STATIC_DIR./web or ./outDirectory containing the Next.js static frontend assets
Example with multiple variables: 
CODEG_PORT=3080 \
CODEG_TOKEN=your-secret-token \
CODEG_DATA_DIR=/var/lib/codeg \
CODEG_STATIC_DIR=/usr/local/share/codeg/web \
codeg-server

​
Reverse proxy and HTTPS

For production use, place Codeg behind a reverse proxy such as nginx or Caddy to terminate TLS and serve it over a custom domain.
Caddy handles HTTPS certificate provisioning automatically. Point your domain at the server, add a Caddyfile entry that proxies to localhost:3080, and Caddy obtains a Let’s Encrypt certificate with no additional configuration.
Example nginx location block: 
location / {
    proxy_pass         http://127.0.0.1:3080;
    proxy_http_version 1.1;
    proxy_set_header   Upgrade $http_upgrade;
    proxy_set_header   Connection "upgrade";
    proxy_set_header   Host $host;
}
The Upgrade and Connection headers are required for WebSocket connections used by Codeg’s real-time event stream.

​
Git and SSH

The Codeg server includes git and ssh for repository operations. You can clone private repositories, commit, and push directly from within the workspace without installing additional tools on the host.