Skip to content

Make the project terminal exec into the agent's container - #12

Merged
maxsoldev merged 1 commit into
mainfrom
fix-project-terminal-container-exec
Oct 9, 2026
Merged

maxsoldev merged 1 commit into
mainfrom
fix-project-terminal-container-exec

Conversation

@maxsoldev

Copy link
Copy Markdown
Collaborator

Part 2 of #7 — the broken project Terminal tab.

Stacked on #10. Base is fix-appx-data-holds-no-project-files, because this builds on the hostProjectRoot / ProjectDir plumbing there. Review #10 first; this retargets to main once it merges.

The problem

The Terminal tab POSTed the host projectDir appx reported ($APPX_DATA/projects/<name>) to /api/shell. In container mode project files live at /workspace/<name> inside the outer container, so that directory never existed and the PTY spawn failed — every click was an HTTP 500.

The fix

You picked "exec into the container" over hiding the tab, so the directory is now resolved server-side from the project ID:

POST /api/projects/{id}/shell
  container mode -> docker exec -i -t -e TERM=xterm-256color \
                      -w /workspace/<name> builder-outer /bin/bash -l
  co-located     -> local PTY with cwd = <projectRoot>/<name>

Only session creation needed to change. Resize and WebSocket I/O still go through /api/shell/{id} and /api/shell/{id}/connect, and in container mode the docker CLI forwards our PTY's size over the exec API, so SIGWINCH reaches the shell inside the container (verified below).

terminal.LocalManager grows CreateCommand(CommandSpec) as the seam between a local login shell and a container exec; Create() is now a thin wrapper over it.

The caller no longer names a path

POST /api/shell previously took a cwd from the request body, so any authenticated caller could open a shell at an arbitrary host path. The project terminal was its only consumer, so that's now gone: the endpoint ignores its body and always opens the appx user's login shell in their home directory.

ContainerShell.CommandFor is the one place a project name becomes a path, so it re-validates the slug — rejecting separators, .., and anything outside [a-z0-9-] — even though names are validated on create. Arguments reach exec as a vector, never through a shell.

New knobs

Env var Effect
APPX_PROJECT_SHELL_CONTAINER Use the container-exec path outside container mode (local dev against a hand-run agent-server container whose workspace isn't bind-mounted)
APPX_PROJECT_SHELL Override the in-container shell (default /bin/bash)

Testing

Unit tests: container_test.go pins the exec argv (workdir, -i -t, TERM, the empty Dir since docker runs on the host), the defaults, and the slug rejection list. shell_handlers_test.go covers both branches plus 404 / 401 / 501 (no backend configured) / 502 (exec can't start) and asserts /api/shell tolerates-but-ignores a cwd body.

Integration against a real container. The production image is amd64-only and this box is arm64, so I ran it against debian:bookworm-slim with a /workspace/myapp — what it exercises is appx's side (exec + PTY attach + resize), which is the part that was broken:

$ APPX_SHELL_TEST_CONTAINER=appx-shell-test go test ./internal/terminal -run ContainerExec_Manual -v
exec: docker exec -i -t -e TERM=xterm-256color -w /workspace/myapp appx-shell-test /bin/bash -l
shell output:
    root@08903cfbe1f4:/workspace/myapp# pwd; ls; tput cols; echo DONE''MARKER
    /workspace/myapp     <- started in the project dir, inside the container
    README.md            <- sees the project's files
    100                  <- the width pushed via Resize() reached the in-container tty
--- PASS

container_manual_test.go is env-gated and skipped by default; setup command is in its doc comment. Happy to drop it if you'd rather not carry skipped tests.

End-to-end via the browser. Real binary, real container, clicking the tab that used to 500:

$ APPX_PROJECT_SHELL_CONTAINER=appx-shell-test ./appx --http --host 127.0.0.1.sslip.io --port 8096
project terminals: exec into container "appx-shell-test" at /workspace

Driving it with Playwright — typed pwd; ls; hostname into the Terminal tab:

root@08903cfbe1f4:/workspace/myapp# pwd; ls; hostname
/workspace/myapp
README.md
08903cfbe1f4        <- the container's hostname, matching docker ps

API checks: 201 with a session id, 404 unknown project, 401 unauthenticated. The server terminal (/shell) still opens the host login shell correctly.

task build, task test, task lint pass.

Not in this PR

--purge-data leaving project volumes behind is the last part of #7 and follows separately.

🤖 Generated with Claude Code

@maxsoldev
maxsoldev deleted the branch main October 9, 2026 09:53
@maxsoldev maxsoldev closed this Oct 9, 2026
@maxsoldev maxsoldev reopened this Oct 9, 2026
@maxsoldev
maxsoldev changed the base branch from fix-appx-data-holds-no-project-files to main October 9, 2026 09:54
The Terminal tab on the project page was a guaranteed HTTP 500 in container
mode. It POSTed the host projectDir appx reported ($APPX_DATA/projects/<name>)
to /api/shell, but project files live at /workspace/<name> *inside* the outer
container, so the directory never existed and the PTY spawn failed.

Rather than hide the tab, make it work. A new project-scoped endpoint resolves
the directory server-side:

  POST /api/projects/{id}/shell
    container mode -> docker exec -i -t -e TERM -w /workspace/<name> \
                        builder-outer /bin/bash -l
    co-located     -> local PTY with cwd = <projectRoot>/<name>

Resize and WebSocket I/O are unchanged: the new route only creates the
session, and /api/shell/{id} and /api/shell/{id}/connect carry the rest. In
container mode the docker CLI forwards our PTY's size over the exec API, so
SIGWINCH reaches the shell inside the container.

The caller no longer names a path. POST /api/shell ignores its body and always
opens the appx user's login shell in their home directory; previously any
authenticated request could open a shell at an arbitrary host path, which the
project terminal was the only consumer of. terminal.LocalManager grows
CreateCommand(CommandSpec) as the seam between a local shell and a container
exec, and Create() is now a thin wrapper over it.

terminal.ContainerShell.CommandFor is the one place a project name becomes a
path, so it re-validates the slug (rejecting separators, traversal and
anything outside [a-z0-9-]) even though names are already validated on create.
Arguments go to exec as a vector, never through a shell.

APPX_PROJECT_SHELL_CONTAINER selects the container-exec path outside container
mode, for local dev against a hand-run agent-server container whose workspace
is not bind-mounted. APPX_PROJECT_SHELL overrides the in-container shell.

Refs #7

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@maxsoldev
maxsoldev force-pushed the fix-project-terminal-container-exec branch from fcd263b to 6c6d112 Compare October 9, 2026 09:54
@maxsoldev
maxsoldev merged commit 361bcaa into main Oct 9, 2026
1 check passed
@maxsoldev
maxsoldev deleted the fix-project-terminal-container-exec branch October 9, 2026 09:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant