From f40124296da7ccd8e5770e4594586a3de5044479 Mon Sep 17 00:00:00 2001
From: Joakim Persson <joakim.persson@icloud.com>
Date: Thu, 9 Apr 2026 14:31:55 +0200
Subject: [PATCH] Add usage section: how to connect and run commands inside the
 container

---
 README.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/README.md b/README.md
index b9102d0..03f8a31 100644
--- a/README.md
+++ b/README.md
@@ -33,6 +33,53 @@ docker compose run --rm devbox
 - **AWS CLI v2** — built-in SSO/Bedrock authentication with headless device-code flow
 - **Multi-arch** — amd64 and arm64
 
+## Usage
+
+### Connecting to the container
+
+From your laptop, SSH into the remote server where Docker is running, then start the container:
+
+```bash
+# 1. SSH into the remote server
+ssh user@remote-server
+
+# 2. Navigate to the project
+cd opencode-devbox
+
+# 3. Start the container with an interactive shell
+docker compose run --rm devbox bash
+
+# You're now inside the container — run commands here
+aws sso login --sso-session <your-sso-session> --use-device-code
+opencode
+```
+
+### Running modes
+
+**Interactive shell** — enter the container, run multiple commands:
+```bash
+docker compose run --rm devbox bash
+```
+
+**Direct to opencode** — skips the shell, launches opencode immediately:
+```bash
+docker compose run --rm devbox
+```
+
+**Background container** — keep it running, attach when needed:
+```bash
+# Start in background
+docker compose up -d
+
+# Attach a shell to the running container
+docker compose exec devbox bash
+
+# Or run a single command inside it
+docker compose exec devbox aws --version
+```
+
+> `run` creates a new container (cleaned up with `--rm`). `exec` attaches to an already running one.
+
 ## Configuration
 
 ### Environment Variables