Real Terminal Access (PTY)

SuperBuilder gives AI agents access to a real terminal through a PTY (pseudo-terminal). This is your actual shell, with your environment variables, your installed tools, your user permissions, and your network access — not a sandboxed simulation.

What PTY Access Means

A PTY is the same kind of terminal interface your Mac's Terminal.app uses. When an agent runs a command through SuperBuilder's terminal, it's running it the same way you would in a terminal window:

• Your environment — $PATH, $HOME, environment variables from your shell profile, all present
• Your installed tools — npm, docker, kubectl, aws, gh, brew — whatever you have installed
• Your permissions — the agent runs as your user, with the same filesystem and network access you have
• Your network — VPN connections, local services, internal network resources — all accessible
• Interactive programs — programs that require terminal interaction (like git commit opening an editor, or npm init asking questions) work correctly

This is meaningfully different from a sandboxed execution environment where the agent gets a clean shell with no tools and no network.

What Agents Can Do with Terminal Access

Run your project's build and test commands — npm test, cargo build, pytest, make — whatever your project uses, the agent can run it and read the output.

Execute database commands — psql, mysql, redis-cli — with your credentials already configured.

Use Git — git status, git log, git diff, branch operations, commits, pushes — all via real git, not an abstraction.

Run Docker — build images, start containers, inspect logs, execute commands inside containers.

Interact with cloud CLIs — deploy via the Heroku CLI, apply Terraform plans, push to AWS, interact with GCP, manage Fly.io apps — using your existing authenticated sessions.

Install dependencies — npm install, pip install, brew install — when a task requires a new tool, the agent can install it.

Script and automate — write shell scripts, make them executable, run them.

Watching Terminal Output

The terminal panel in SuperBuilder shows the real-time output of everything the agent runs. You can watch commands execute, see test output as it streams, and read error messages exactly as they appear in a real terminal.

You can also interact with the terminal directly — type commands yourself alongside what the agent is running, or take over when you want to guide a specific step manually.

Long-Running Commands

The PTY handles long-running commands naturally — database migrations that take 5 minutes, test suites that run for 10 minutes, build processes that compile thousands of files. The agent waits for the command to complete and reads the full output before continuing.

For very long-running commands, the agent can also run them in the background and check back on the output later.

Safety and Control

Real terminal access is powerful — and that means it's worth thinking about what you're giving the agent access to.

SuperBuilder shows you every command the agent is about to run before executing it. You can review, modify, or cancel any command. By default, some categories of commands (like rm -rf, or anything that touches system directories) require explicit confirmation.

You can configure per-workspace rules:

• Allowed commands — only specific commands can run without confirmation
• Blocked commands — certain commands require your approval every time
• Notification on writes — get notified when the agent runs any command that modifies the filesystem

For most development work, you can run in a relaxed mode where the agent executes freely. For production access or sensitive work, you tighten the approval requirements.

Terminal Access vs. Cloud Execution

Real terminal access is a local feature — it runs on your machine. When agents run in the cloud (via SuperBuilder's cloud runners), they get a cloud terminal with a clean environment instead.

For tasks that require your local environment — your VPN, your local credentials, your locally installed tools — local execution with real terminal access is the right choice. For tasks that should run unattended or in a clean environment, cloud execution is better.

Frequently Asked Questions

Can the agent see my environment variables?

Yes. The agent's terminal session has access to the same environment variables as your shell. Be aware that this includes any secrets or credentials in your environment.

Can the agent run sudo commands?

The agent can run sudo if your user has sudo access, but all sudo commands require explicit confirmation by default. You can tighten this further in settings.

Does the agent have access to my SSH keys?

The SSH agent in your shell session is accessible, so if you've loaded your SSH key into the SSH agent (ssh-add), the agent can use it for git operations. Direct access to key files requires the agent to be able to read ~/.ssh/, which it can since it runs as your user.

Can I watch what the agent is typing into the terminal?

Yes. The terminal panel shows every command the agent runs and its full output, in real time.

What happens if a command hangs?

You can interrupt any running command from the terminal panel — the same as pressing Ctrl+C in a regular terminal. The agent handles interrupted commands and decides how to proceed.