open-harness/docs/connecting.md

id, slug, sidebar_position, title

id	slug	sidebar_position	title
connecting	/connecting	4	Connecting to the Sandbox

Connecting to the Sandbox

The sandbox is a Docker container running on your host (or a remote server). Getting UI apps like the docs site and T3 Code onto your laptop browser depends on how you connect — not every connection method forwards ports. This page covers your options, explains which one to use, and walks an end-to-end recipe.

Three ways to connect

Option	Command / action	Port forwarding to laptop
A — Terminal	make shell from the host	None — plain shell only
B — VSCode Attach (local)	Dev Containers extension → "Attach to Running Container" → openharness	Automatic while attached
C — VSCode Remote-SSH + Attach (remote host)	SSH into your host in VSCode, then Attach to Container	Automatic while attached

Option A — Terminal

cd ~/.openharness
make shell

You land inside the container as the sandbox user. This is enough to run CLI agents and configure Slack. Container ports are not forwarded to your laptop — you cannot open localhost:3000 in your browser via this method alone.

Option B — VSCode Attach to Running Container (local host)

1. Install the Dev Containers extension.
2. Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) → Dev Containers: Attach to Running Container.
3. Select openharness.

VSCode opens a remote window connected to the container and automatically forwards container ports to localhost on your laptop for the duration of the session.

Option C — VSCode Remote-SSH + Attach (remote host)

If the sandbox runs on a remote server:

1. Connect to the server via Remote-SSH in VSCode.
2. From that SSH window, follow Option B to attach to the openharness container.

Port forwarding works identically — VSCode tunnels the container ports through the SSH connection to your laptop localhost. No manual ssh -L required.

Why VSCode Attach is the recommended path

Attaching via VSCode is the easiest way to reach container UIs on your laptop browser. The auto-forwarding is session-scoped: ports appear under the Ports panel while attached and disappear when you close or detach from the VSCode window.

If you only need a terminal (no browser UI), Option A is fine.

What happens when you close VSCode

When you close the VSCode remote window or detach from the container, the port forwards drop. Apps in tmux keep running inside the container — they are unaffected — but localhost:<port> on your laptop no longer resolves until you re-attach.

Default exposure posture

The sandbox publishes one port by default:

127.0.0.1:1455:1455   # Pi harness OAuth login callback (host loopback only)

Nothing else is published to the host. The 127.0.0.1 binding ensures port 1455 is reachable from localhost on the host machine — which VSCode's Remote-SSH forwarding can carry back to your laptop — without exposing it on any public interface.

All other container ports (3000, 3773, etc.) are only reachable via VSCode's auto-forwarding or a manual ssh -L tunnel.

Opt-in public exposure

If you need a port reachable beyond your laptop — for example, to share a preview with a teammate — there are two opt-in paths:

1. Compose overlay binding 0.0.0.0

Add a custom compose file that binds the port on all interfaces and merge it in with composeOverrides[] in config.json:

# docker-compose.my-expose.yml
services:
  sandbox:
    ports:
      - "0.0.0.0:3000:3000"

This is NOT the default; you opt in explicitly. Be aware that binding to 0.0.0.0 exposes the port on the host's public interface.

2. External tunnel

The harness ships no built-in tunnel tool. For public access, bring your own: cloudflared, ngrok, tailscale funnel, or an nginx/Caddy reverse proxy. Start the tunnel inside the sandbox in a named tmux session (see tmux conventions).

tmux session naming

All long-running processes inside the sandbox run in named tmux sessions. The naming convention is <category>-<identifier>:

Category	Example	Purpose
client-	client-slack, client-discord	External-surface clients bridging an in-sandbox agent
agent-	agent-watcher, agent-batch	Headless / long-running agent processes (interactive CLIs are foreground, not tmux)
app-	app-docs, app-api	Dev servers

For the full convention see context/rules/sandbox-processes.md.

End-to-end recipe

This recipe assumes the sandbox is already running (make ps confirms the openharness container is up). Steps run inside the sandbox unless noted.

Step 1 — Attach via VSCode

Follow Option B (or C for a remote host). The Ports panel in VSCode shows forwarded ports as you launch apps.

Step 2 — Configure Slack

# Inside the sandbox (already attached via VSCode or make shell)
oh config slack

The interactive wizard collects your Slack tokens, validates them, writes .devcontainer/.env, and restarts the client-slack tmux session in Socket Mode. For the full wizard walkthrough see Integrations → Slack.

After the wizard completes, verify the bridge is live:

tmux capture-pane -t client-slack -p | grep -i 'connected\|listening'

Step 3 — Launch T3 Code

T3 Code is not preinstalled; the first invocation downloads it via npx.

tmux new-session -d -s agent-t3code 'npx t3 2>&1 | tee /tmp/agent-t3code.log'
tmux attach -t agent-t3code

Watch the session output — T3 Code prints a pairing URL. Open that URL in your browser to complete the browser-based pairing step. After pairing, the UI is available at localhost:3773 on your laptop (via VSCode auto-forwarding).

Detach from the tmux session without stopping it: Ctrl-b d.

For more on T3 Code setup see Harnesses → T3 Code.

Step 4 — Launch the docs site

tmux new-session -d -s app-docs 'pnpm --filter @openharness/docs start 2>&1 | tee /tmp/app-docs.log'

The Docusaurus dev server binds port 3000 inside the container. Via VSCode auto-forwarding, open localhost:3000 in your laptop browser.

Step 5 — Confirm ports in VSCode

Open the Ports panel (bottom status bar → Ports, or Ctrl+Shift+P → "Focus on Ports"). You should see:

Port	Forwarded to	App
1455	localhost:1455	Pi OAuth callback
3000	localhost:3000	Docs site
3773	localhost:3773	T3 Code UI

If a port is missing, confirm the tmux session is running (tmux ls) and that you are still attached via VSCode.

Quick-reference: reach localhost from your laptop

App	Container port	Laptop URL (VSCode attached)
Docs site	3000	http://localhost:3000
T3 Code UI	3773	http://localhost:3773
Pi OAuth callback	1455	http://localhost:1455