feat(server): add headless Docker image

[moenzuel]

Problem

Running the published T3 server in a fresh container requires downloading the package and compiling native dependencies at startup. Keeping that compiler toolchain in the runtime image also makes a headless deployment larger and less predictable.

Solution

• Add a multi-stage Dockerfile that installs an exact published T3 package during the image build.
• Keep compilers in the builder stage and run the server as the non-root node user behind tini.
• Include CA certificates for Git HTTPS and trust the intentionally mounted /workspace path.
• Let explicit headless auto-bootstrap configuration override the headless default, and use it to register the Docker workspace on startup.
• Persist T3 state and the workspace through dedicated volumes.
• Document build, run, persistence, provider CLI, and host filesystem permission requirements.

Impact

Users can build a repeatable headless T3 server image that starts without an npm download and opens with the mounted workspace ready as a project. Provider CLIs and credentials remain an explicit deployment choice rather than being baked into the base image.

Validation

• vp test run apps/server/src/cli/config.test.ts
• vp test run apps/server/src/serverRuntimeStartup.test.ts
• vp run t3#typecheck
• vp lint apps/server/src/cli/config.ts apps/server/src/cli/server.ts apps/server/src/cli/config.test.ts
• vp fmt --check apps/server/src/cli/config.ts apps/server/src/cli/server.ts apps/server/src/cli/config.test.ts docs/user/remote-access.md
• docker build --check --build-arg T3_VERSION=0.0.33 .
• docker build --build-arg T3_VERSION=0.0.33 --tag t3-pr4911-review:local .
• Confirmed Git HTTPS access and Git status against a root-owned mounted repository while the container runs as UID 1000.

Built with GPT-5.6 using the Codex harness in T3 Code.

Note

Add headless Docker image for the T3 server

• Adds a multi-stage Dockerfile that installs the published T3 server via npm, with Git, SSH client, and tini in the runtime image. Exposes port 3773 and declares volumes for /data and /workspace.
• Adds a Docker section to remote-access.md covering build/run examples, credential setup, and UID/GID considerations for bind mounts.
• Fixes autoBootstrapProjectFromCwd precedence in headless mode: flags and environment variables can now opt in to auto-bootstrap rather than being hard-disabled by the t3 serve command.

^{Macroscope summarized ebc1486.}

---

Note

Low Risk
Packaging and CLI precedence changes with tests; no auth or data-model changes; Docker runs as non-root with documented volume/permission caveats.

Overview
Adds a multi-stage Dockerfile that installs the published t3 npm package at build time (T3_VERSION build arg, default latest), keeps build tooling out of the runtime image, and runs t3 serve as the non-root node user on 0.0.0.0:3773 with --auto-bootstrap-project-from-cwd, /data and /workspace volumes, Git/SSH, and tini.

Headless CLI behavior no longer hard-disables auto-bootstrap via forceAutoBootstrapProjectFromCwd. t3 serve still defaults auto-bootstrap off in headless mode, but an explicit flag or env can opt in—matching what the Docker image needs to register the mounted workspace on first start.

Documents build/run, persistence, UID 1000:1000, and provider CLI expectations in the remote-access guide.

^{Reviewed by Cursor Bugbot for commit ebc1486. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: f38ed540-8e85-4d4a-a58d-404e0175214d

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4caec2c062

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR adds new Docker deployment capability and changes the auto-bootstrap configuration precedence to allow explicit opt-in during headless mode. New features with runtime behavior changes warrant human review. There's also an unresolved comment about Docker networking causing unreachable pairing URLs.

^{You can customize Macroscope's approvability policy. Learn more.}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Want fixes drafted automatically? Bugbot Autofix can create code changes for findings. A team admin can enable Autofix in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit ebc1486. Configure here.}

[cursor]

Unreachable Docker pairing URLs

Medium Severity

The image runs t3 serve with --host 0.0.0.0, so headless pairing advertises the container bridge IP from resolveHeadlessConnectionHost. With the documented -p 3773:3773 publish path, that URL and QR code are not reachable from the host (especially Docker Desktop) or other devices, while bind host and advertised host remain the same setting, so T3CODE_HOST cannot fix it without replacing the full CMD.

Additional Locations (1)

• docs/user/remote-access.md#L120-L127

 

^{Reviewed by Cursor Bugbot for commit ebc1486. Configure here.}