cokaremote/tunneling/README.md

workmachine

A long-running Ubuntu development machine controlled through cokacremote MCP.

On first start, workmachine creates /shared/AGENTS.md from templates/AGENTS.md if the file does not already exist. Existing instructions are never overwritten.

Configure

Run commands from the directory containing docker-compose.yml:

cd /absolute/path/to/workmachine
cp .env.example .env

Set these values in .env:

• SHARED_PATH: absolute host directory mounted at /shared
• MCP_PUBLIC_URL: public HTTPS base URL without /mcp
• CLOUDFLARE_TUNNEL_TOKEN: Cloudflare Tunnel token

Example for macOS:

SHARED_PATH=/Users/yourname/Documents/workspace
MCP_PUBLIC_URL=https://example.com
CLOUDFLARE_TUNNEL_TOKEN=replace-with-your-real-tunnel-token
TZ=Asia/Seoul
COKACREMOTE_REF=main

This example creates the public MCP endpoint https://example.com/mcp. Use an absolute path for SHARED_PATH, do not add a trailing slash to MCP_PUBLIC_URL, and never commit the populated .env file.

In the Cloudflare Tunnel public-hostname settings, set the service URL to:

http://localhost:2999

Start

From the directory containing docker-compose.yml:

cd /absolute/path/to/workmachine
docker compose -p workmachine up -d --build
docker compose -p workmachine ps
docker compose -p workmachine logs -f

To rebuild without reusing layers from previous Docker builds, then recreate the containers from the new image:

docker compose -p workmachine build --no-cache --pull
docker compose -p workmachine up -d --force-recreate

This keeps the existing cokacremote-state volume and its OAuth state.

To run from any directory, specify both the Compose file and environment file:

docker compose -p workmachine -f /absolute/path/to/workmachine/docker-compose.yml --env-file /absolute/path/to/workmachine/.env up -d --build

Nginx listens on port 2999 and forwards cokacremote routes to port 3000.

Read the generated OAuth approval key:

docker compose -p workmachine exec workmachine cat /var/lib/cokacremote/oauth-approval-key

Add an application route

Create a file under ${SHARED_PATH}/nginx/routes.d, for example 20-newapp.conf:

location = /newapp {
    return 308 /newapp/;
}

location ^~ /newapp/ {
    include /etc/nginx/snippets/workmachine-proxy.conf;
    proxy_pass http://127.0.0.1:5000/;
}

Validate and reload without restarting the container:

docker compose -p workmachine exec workmachine nginx -t
docker compose -p workmachine exec workmachine nginx -s reload