Repository navigation
Make the project terminal exec into the agent's container - #12
Merged
Merged
Conversation
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
force-pushed
the
fix-project-terminal-container-exec
branch
from
October 9, 2026 09:54
fcd263b to
6c6d112
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Part 2 of #7 — the broken project Terminal tab.
The problem
The Terminal tab POSTed the host
projectDirappx 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:
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, soSIGWINCHreaches the shell inside the container (verified below).terminal.LocalManagergrowsCreateCommand(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/shellpreviously took acwdfrom 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.CommandForis 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 reachexecas a vector, never through a shell.New knobs
APPX_PROJECT_SHELL_CONTAINERAPPX_PROJECT_SHELL/bin/bash)Testing
Unit tests:
container_test.gopins the exec argv (workdir,-i -t, TERM, the emptyDirsince docker runs on the host), the defaults, and the slug rejection list.shell_handlers_test.gocovers both branches plus 404 / 401 / 501 (no backend configured) / 502 (exec can't start) and asserts/api/shelltolerates-but-ignores acwdbody.Integration against a real container. The production image is amd64-only and this box is arm64, so I ran it against
debian:bookworm-slimwith a/workspace/myapp— what it exercises is appx's side (exec + PTY attach + resize), which is the part that was broken:container_manual_test.gois 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:
Driving it with Playwright — typed
pwd; ls; hostnameinto the Terminal tab:API checks:
201with a session id,404unknown project,401unauthenticated. The server terminal (/shell) still opens the host login shell correctly.task build,task test,task lintpass.Not in this PR
--purge-dataleaving project volumes behind is the last part of #7 and follows separately.🤖 Generated with Claude Code