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. Each command you type is sent to the sandbox as a standalone execution. Think of it like running one-off commands remotely rather than having a continuous SSH session.

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 project's root directory.
4. The output (stdout/stderr) is displayed in the terminal area above.

Prerequisites

Sandbox State	Terminal Works?
Running (task in progress)	✅ Yes
Warm window (task completed, <5 min ago)	✅ Yes
Keep-alive enabled	✅ Yes — sandbox stays alive for manual use
Sandbox reclaimed/stopped	❌ No — "Failed to connect to sandbox"

Key Differences from a Normal Terminal

Understanding these differences will save you frustration:

Each command is independent

Unlike a normal shell where you type cd src && ls, the terminal doesn't maintain a persistent shell session between commands. Every command starts fresh in your project's root directory (/home/vercel-sandbox/project).

What this means in practice:

# ✅ This works — single compound command
ls src && cat src/index.ts

# ✅ This works — cd within the same command
cd src && ls

# ⚠️ This won't persist — cd alone doesn't carry over
cd src        # Runs, but...
ls            # ...this still runs from project root

Workaround: Chain commands

To work in a subdirectory, chain your commands with && or ;:

cd src && ls -la
cd build && cat output.js

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
"Failed to connect to sandbox"	Sandbox has been reclaimed	Enable Keep Alive before starting the task, or send a follow-up to get a new sandbox
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
cd doesn't persist	Expected behavior	Chain commands: cd src && ls instead of separate cd then ls
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.