arqbound-remote-exec

Proof-of-Concept (PoC) architecture demonstrating an AI coding agent executing entirely inside a remote ephemeral Docker container while streaming interactive stdin, stdout, and stderr (stdio/TTY) seamlessly to a developer's local terminal via an SSH gateway connection.

---

Technical Overview & Architecture

This architecture explicitly replaces the traditional model of running AI coding agents locally and invoking remote tools over APIs. Instead, the agent process, runtime environment, tools, and project workspace reside fully inside an isolated remote environment.

+-------------------+             SSH Connection (PTY / stdio)            +-----------------------------------+
| Developer Laptop  | --------------------------------------------------> | Remote Host Server                |
|                   |                                                     |                                   |
| Thin client:      | <-------------------------------------------------- | 1. Go SSH Gateway Proxy           |
| `ssh arq-runner`  |                                                     | (Accepts SSH, authenticates)      |
+-------------------+                                                     |                                   |
                                                                          | v Spawns / Execs                  |
                                                                          | 2. Target Container (gVisor/Docker)|
                                                                          | +-------------------------------+ |
                                                                          | | Agent Process (bash / CLI)    | |
                                                                          | | Workspace: /workspace         | |
                                                                          | +-------------------------------+ |
                                                                          +-----------------------------------+

---

Directory Structure

arqbound-remote-exec/
├── docker-compose.yml        # Service orchestration (gateway & agent-sandbox)
├── README.md                 # Complete system reference & quickstart
├── gateway/
│   ├── Dockerfile            # Multi-stage Docker build for Go SSH Gateway server
│   ├── go.mod                # Go module dependencies
│   ├── go.sum                # Go checksums
│   └── main.go               # SSH daemon leveraging golang.org/x/crypto/ssh & Docker SDK
├── sandbox/
│   ├── Dockerfile            # Target environment with CLI tools, Node, Python
│   └── agent-runner.sh       # Mock interactive agent execution script
├── scripts/
│   └── setup-ssh.sh          # Helper script to generate local test keys and SSH config
└── test-workspace/           # Local folder mounted read-write to /workspace inside sandbox

---

Requirements

• Docker and Docker Compose (docker-compose or docker compose)
• OpenSSH client (ssh)
• Go 1.21+ (only if building/testing gateway binary outside of Docker)

---

Complete Quickstart & Testing Guide

1. Boot Environment

Build and launch the gateway and target sandbox containers:

docker-compose up --build -d

Check running container status:

docker-compose ps

---

2. Generate Local SSH Keypair

Run the SSH setup script to generate a test RSA key (~/.ssh/arqbound_test_key):

./scripts/setup-ssh.sh

Ensure your local ~/.ssh/config file includes:

Host arq-runner
    HostName localhost
    Port 2222
    User dev
    IdentityFile ~/.ssh/arqbound_test_key
    RequestTTY yes
    StrictHostKeyChecking no
    UserKnownHostsFile /dev/null

---

3. Interactive Remote Agent Execution

Connect to the remote agent container via SSH:

ssh arq-runner

Or directly without SSH config:

ssh -i ~/.ssh/arqbound_test_key -p 2222 -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null dev@localhost

Interactive Commands to Try:

• help - Show available mock agent commands.
• status - Check python, node, and OS environment information inside sandbox.
• create hello.py print("Hello ArqBound Remote Exec") - Create a script in /workspace.
• read hello.py - Display file content.
• python3 hello.py - Run the python script inside sandbox.
• exit - Disconnect cleanly.

Workspace Mirroring Check: Verify on your host machine that ./test-workspace/hello.py exists and matches the file created remotely.

---

4. Non-Interactive Command Execution

Test running a single non-interactive command remotely over SSH:

ssh arq-runner "python3 -c 'import os; print(os.listdir(\"/workspace\"))'"

Expected Result: Returns file list in /workspace and exits with code 0.

---

Implementation Details

1. Go SSH Gateway Server (gateway/main.go):

   • Listens on port 2222.
   • Uses golang.org/x/crypto/ssh for SSH protocol handling.
   • Connects to host Docker engine via github.com/docker/docker/client.
   • Attaches to target container using ContainerExecCreate and ContainerExecAttach.
   • Handles window size changes (window-change / SIGWINCH), PTY allocation, and demuxes stdout/stderr for non-TTY execution.
   • Forwards container process exit codes to SSH client via exit-status SSH request.

2. Target Sandbox Container (sandbox/Dockerfile):

   • Isolated Ubuntu environment with python3, nodejs, git, curl, jq, and standard CLI tools.
   • /workspace directory mounted to host ./test-workspace.