SYD-PTY(1)

📦
version 3.59.0 · 3 versions
, in arch rolling

💅 syd-pty — bestie's guide to the PTY-to-STDIO glow-up

okay so welcome to SYD-PTY(1), from the General Commands Manual section 1, and honestly? this little icon is a PTY to STDIO bidirectional forwarder and it's lowkey doing the most. let me walk you through it 🫶

✨ NAME ✨

syd-pty — a PTY to STDIO bidirectional forwarder. that's it, that's the vibe: it takes data from one side and forwards it to the other, both directions, no cap 💫

🌸 SYNOPSIS 🌸

syd-pty [-dh] -i <pty-fd> [-x <x-size>] [-y <y-size>]

like, that's the whole summoning ritual. -i is the only thing you truly need 💅

🦋 DESCRIPTION 🦋

Forwards data between the given pty(7) main file descriptor and stdio(3).

literally just that. it's a little relay goblin sitting between your terminal and your standard in/out/err, passing bytes back and forth like notes in class 💌

🎀 OPTIONS 🎀

  • -h — Display help. your little "what do" button 🥺
  • -d — Run in debug mode without confinement. heads up: this is permitted only if Syd is built with the trusted Cargo feature. so like, not always an option, check first 🚨
  • -i pty-fd — PTY main file descriptor. the main character argument, fr fr 👑
  • -x x-size — Specify window row size (default: inherit). ✨
  • -y y-size — Specify window column size (default: inherit). ✨

🌈 USAGE 🌈

okay bestie, real talk: syd-pty(1) is not meant to be used as a standalone tool. it's not that kind of girl. Syd invokes syd-pty(1) at startup when PTY sandboxing is set to on with sandbox/pty:on. for the full tea, see the PTY SANDBOXING section in the syd(7) manual page 📖

but if you do want to use syd-pty(1) in your own project? absolutely slay, here's how: create a new pseudoterminal with posix_openpt(3) or openpty(3) and pass the main end of the file descriptor pair to syd-pty(1) with the -i <pty-fd> argument. easy 💅

🚨 important caveat, do not skip this: syd-pty(1) is going to set the terminal to raw mode and makes no attempt to save/reset original terminal settings — that's the caller's responsibility. so like, your terminal, your problem, no takebacks 😭

🧚 IMPLEMENTATION 🧚

syd-pty(1) is designed for performance, security, and privacy, and it ate, honestly:

  • it uses edge-triggered epoll(7) for event notification ⚡
  • fully asynchronous operations to handle pseudoterminal activities without blocking
  • it transfers data with zero-copy splice(2), moving bytes directly between file descriptors within the kernel without exposing plaintext in user space — privacy queen 🔐
  • two pairs of pipes carry bidirectional traffic between pty(7) and stdio(3) 🚰
  • the execution environment is confined with seccomp(2) and landlock(7), restricting system calls and file access to the minimum required

like the way it just... does all that. obsessed 🫶

🔥 SECURITY 🔥

syd-pty(1) applies multiple confinement layers to mitigate risks associated with running outside the Syd sandbox, preventing potential Meddler-in-the-Middle (MITM) attacks against containers. not today, meddler 💀

here's the stack, bestie:

  • Linux capabilities(7) are dropped early and the no-new-privs attribute is set, so no unwanted capability leaks into the process
  • the TOSTOP flag is set for the terminal syd-pty(1) reads from, to disable background processes from writing
  • resource limits — RLIMIT_CORE, RLIMIT_FSIZE, RLIMIT_NOFILE, RLIMIT_NPROC, RLIMIT_LOCKS, RLIMIT_MEMLOCK, and RLIMIT_MSGQUEUE — are set to zero to prevent core dumps and file/fd/process/msgqueue creation inside the main loop
  • seccomp(2) filters are configured to allow only required syscalls — and that list excludes memory, file system and network system calls 🚫
  • landlock(7) and namespaces(7), if available, enforce further restrictions by disallowing all filesystem and network access, providing an additional layer of security
  • the root directory is moved into /proc/self/fdinfo with pivot_root(2) and the old root is detached with MNT_DETACH, so no path to the host filesystem remains in the mount namespace 🕳️

these combined techniques ensure that even if syd-pty(1) is compromised, the scope of malicious actions is significantly limited, maintaining integrity and security of the system. that's the whole point, and it's giving fortress 🏰✨

💜 ENVIRONMENT 💜

  • SYD_PTY_DEBUG — Run in debug mode without confinement, equivalent to the -d option. heads up: this is ignored unless Syd is built with the trusted Cargo feature 🙈

💀 BUGS 💀

okay so this one's a whole saga. splice(2) support for ttys was removed in commit 36e2c7421f02a22f71c9283e55fdb672a9eb58e7 (merged for Linux 6.5) and later restored in commit 9bb48c82aced07698a2d08ee0f1475a6c4f6b266 (merged for Linux 6.6) 😭

when running under a problematic Linux kernel, syd-pty(1) will exit with 22, aka EINVAL or Invalid argument. so if you're getting ghosted by exit code 22, that's why, it's the kernel not you 🫂

see following links for more information:

⭐ SEE ALSO ⭐

syd(1), syd(2), syd(7), stdio(3), pty(7)

syd homepage: https://sydbox.exherbo.org/

👑 AUTHORS 👑

Maintained by Ali Polatel. Up-to-date sources can be found at https://gitlab.exherbo.org/sydbox/sydbox.git and on Radicle at rad:z38HCnbmcDegA2BMxuPaPRPMdp6wF. Bugs/patches can be submitted to https://gitlab.exherbo.org/groups/sydbox/-/issues. Discuss in #sydbox on Libera Chat or in #sydbox:mailstation.de on Matrix 💬

and that's the whole page bestie 🎀 this was the General Commands Manual edition, dated 2026-09-01 — periodt, go forward some PTYs responsibly 🌸💅✨

📦 where this page comes from