Skip to content

Secure, Fast, and Extensible Sandbox runtime for AI agents.

feat(execd): default TERM=xterm-256color for PTY sessions

高然ba5a13a92206
diff --git a/components/execd/PTY.md b/components/execd/PTY.md
index b4e8ba167..fd15f0757 100644
--- a/components/execd/PTY.md
+++ b/components/execd/PTY.md
@@ -40,6 +40,8 @@ Use this when you need a **long-lived shell** driven over **WebSocket**: PTY mod
## Notes
+- PTY sessions default `TERM=xterm-256color` when the sandbox environment has no usable `TERM`, so colors and terminfo-aware programs work out of the box. An explicit `TERM` always wins. Pipe mode does not get a `TERM` default.
+- Shell startup flags are `--noprofile --norc`, so image shell rc files (prompt, aliases, `ls --color=auto`) do not load; configure colors explicitly per program when needed.
- Commands running under the `sh` fallback must use syntax supported by the image's `sh` implementation.
- Output is also buffered for **replay**; reconnect with `since=` to catch up.
- Viewer output is delivered from the bounded replay stream, so WebSocket backpressure from a slow viewer cannot block the read/write holder's live output pipe. In pipe mode this is a combined stream without separate stdout/stderr channels.
diff --git a/components/execd/pkg/runtime/env_test.go b/components/execd/pkg/runtime/env_test.go
index 6fc26a5b2..5dd9e4b80 100644
--- a/components/execd/pkg/runtime/env_test.go
+++ b/components/execd/pkg/runtime/env_test.go
@@ -307,3 +307,33 @@ func TestUserProcessEnvironmentFiltersBlacklist(t *testing.T) {
require.Contains(t, joined, "OPENSANDBOX_ID=sandbox-1")
require.NotContains(t, joined, "EXECD_ACCESS_TOKEN")
}
+
+func TestPTYSessionEnvDefaultsTerm(t *testing.T) {
+ t.Setenv("EXECD_ENVS", "")
+ applyTestBinding(t, &binding.RuntimeBinding{SandboxID: "sandbox-1"})
+
+ t.Setenv("TERM", "")
+ require.Equal(
+ t,
+ []string{"TERM=" + defaultPTYTerm},
+ terminalEntries(ptySessionEnv()),
+ )
+}
+
+func TestPTYSessionEnvKeepsExistingTerm(t *testing.T) {
+ t.Setenv("EXECD_ENVS", "")
+ applyTestBinding(t, &binding.RuntimeBinding{SandboxID: "sandbox-1"})
+
+ t.Setenv("TERM", "xterm")
+ require.Equal(t, []string{"TERM=xterm"}, terminalEntries(ptySessionEnv()))
+}
+
+func terminalEntries(env []string) []string {
+ var found []string
+ for _, kv := range env {
+ if strings.HasPrefix(kv, "TERM=") {
+ found = append(found, kv)
+ }
+ }
+ return found
+}
diff --git a/components/execd/pkg/runtime/pty_session.go b/components/execd/pkg/runtime/pty_session.go
index 150f45a2b..f106670a7 100644
--- a/components/execd/pkg/runtime/pty_session.go
+++ b/components/execd/pkg/runtime/pty_session.go
@@ -23,6 +23,7 @@ import (
"io"
"os"
"os/exec"
+ "strings"
"sync"
"sync/atomic"
"syscall"
@@ -246,6 +247,30 @@ func buildPTYCommand(command string) *exec.Cmd {
return exec.Command(shell, args...)
}
+// defaultPTYTerm is the terminal type assumed for PTY sessions when the
+// resolved environment carries no TERM. Interactive programs (ls, vim, top)
+// consult TERM to decide whether colors and terminfo capabilities are safe
+// to use; execd runs as a daemon whose environment normally lacks it.
+const defaultPTYTerm = "xterm-256color"
+
+// ptySessionEnv returns the user process environment for a PTY session,
+// defaulting TERM when absent or empty (an empty TERM makes programs behave
+// as if terminfo were unavailable). Pipe mode deliberately does not get this
+// default: its side is not a terminal, so advertising one would be wrong.
+func ptySessionEnv() []string {
+ env := UserProcessEnvironment()
+ for i, kv := range env {
+ if name, value, ok := strings.Cut(kv, "="); ok && name == "TERM" {
+ if value != "" {
+ return env
+ }
+ env[i] = "TERM=" + defaultPTYTerm
+ return env
+ }
+ }
+ return append(env, "TERM="+defaultPTYTerm)
+}
+
// StartPTY launches the preferred shell via pty.StartWithSize.
// Must be called with the WS lock held.
func (s *ptySession) StartPTY() error {
@@ -261,8 +286,9 @@ func (s *ptySession) StartPTY() error {
cmd := buildPTYCommand(s.command)
// Resolve through the shared user-env layering (sandbox binding envs from
- // /init < EXECD_ENVS file) instead of inheriting execd's raw environment.
- cmd.Env = UserProcessEnvironment()
+ // /init < EXECD_ENVS file) instead of inheriting execd's raw environment,
+ // and make sure the interactive shell has a usable terminal type.
+ cmd.Env = ptySessionEnv()
if s.cwd != "" {
cmd.Dir = s.cwd
}