Terminal

The Terminal in your Task Workspace gives you direct command-line access to the sandbox environment where your agent is working. It appears at the bottom of the workspace alongside the Logs tab.

How It Works

The terminal is not a traditional persistent shell process. Each command you type is sent to the sandbox as a standalone execution. But it feels like one where it matters: your working directory carries over between commands, so cd behaves the way you expect.

Here's what happens when you type a command:

1. You type a command in the input field at the bottom (next to the $ prompt).
2. Press Enter to execute.
3. The command is sent to the sandbox and executed via sh -c "your command" in your current working directory (you start in the project root, /vercel/sandbox/project).
4. The output (stdout/stderr) is displayed in the terminal area above, and the prompt updates to whatever directory the command ended in.

Prerequisites

Sandbox State	Terminal Works?
Running (task in progress)	✅ Yes
Warm window (after completion, extended while you're actively using the workspace)	✅ Yes
Keep-alive enabled	✅ Yes, sandbox stays alive for manual use
Sandbox reclaimed/stopped	❌ No, the terminal will tell you to send the agent a follow-up message, which wakes the sandbox and reconnects the terminal

Key Differences from a Normal Terminal

Understanding these differences will save you frustration:

Your directory persists, your environment doesn't

The working directory carries over between commands: cd src followed by ls lists src, exactly like a normal shell, and even cd a && cd b lands you where you'd expect. What does not carry over is shell state other than the directory: environment variables, aliases, and shell functions reset with every command.

# ✅ cd persists across commands
cd src        # prompt now shows .../project/src
ls            # lists src, as you'd expect

# ⚠️ Environment variables don't persist
export FOO=1  # Runs, but...
echo $FOO     # ...prints nothing, new shell, fresh environment

# ✅ Workaround: set and use in one command
FOO=1 node script.js
export FOO=1 && echo $FOO

No interactive programs

The terminal doesn't support interactive programs that require ongoing input. Commands that run and exit work perfectly. Long-running commands (like npm run dev) will execute but may time out or not stream output in real-time.

# ✅ Works great
ls -la
cat package.json
npm install
git status
git log --oneline -5
node -e "console.log('hello')"

# ⚠️ May not work as expected
vim file.txt          # No interactive editor support
npm run dev           # Long-running; won't stream real-time output
top                   # Interactive; won't render properly

Keyboard Shortcuts

Key	Action
Enter	Execute the current command
↑ Up Arrow	Navigate to previous command in history
↓ Down Arrow	Navigate to next command in history
Tab	Autocomplete file/directory names

Common Use Cases

Inspect the project structure

find . -type f -name "*.ts" | head -20
ls -la src/
cat package.json | head -30

Check git status

git status
git log --oneline -10
git diff --stat

Run quick scripts

node -e "console.log(require('./package.json').version)"
npx tsc --noEmit 2>&1 | head -20

Install a dependency

npm install lodash
pnpm add dayjs

Check environment

node --version
npm --version
which python
echo $PATH

Debug build issues

npm run build 2>&1 | tail -30
cat .env
ls node_modules/.package-lock.json

Troubleshooting

Issue	Cause	Solution
"No sandbox found for this task"	Sandbox hasn't been created yet	Wait for the agent to start, or send a follow-up message to spin up a new sandbox
"The sandbox for this task has stopped…"	Sandbox has been reclaimed	Send the agent a follow-up message; it wakes the sandbox from your branch, and the terminal reconnects
Command seems to hang	Long-running command or large output	The command may still be executing. Wait a moment, there's a loading indicator next to the $ prompt
Environment variable "disappeared"	Each command runs in a fresh shell	Set and use in one command: FOO=1 node script.js
No output returned	Command may have written to stderr only	Check if the output appears in red (stderr). Some tools write warnings to stderr

Tips

• Copy output: You can select and copy text from the terminal output.
• Clear the terminal: Use the trash icon in the terminal toolbar to clear the history.
• Use the agent instead: For complex multi-step operations, it's often easier to ask the agent: "Run the test suite and show me any failures" rather than typing commands yourself.
• Check Logs first: The Logs tab (next to Terminal) shows what the agent has been doing, including commands it ran. You might find the info you need there without running anything yourself.