Shell Access
Execute commands inside running containers directly from the dashboard.
What is Shell Access?
Shell access lets you open an interactive terminal session into any running container in your deployment. It works like docker exec -it but through the browser, giving you a live shell without needing SSH or direct provider access.
Common use cases:
- Debugging - Inspect processes, check environment variables, test network connectivity
- Log inspection - Read log files that aren't captured by the streaming log system
- One-off commands - Run database migrations, seed scripts, or cache flushes
- File inspection - Check mounted volumes, verify config files, inspect file permissions
Connecting to a Shell
Open your deployment
Navigate to your deployment's detail page from the dashboard.
Go to the Shell tab
Click the Shell tab in the deployment detail view.
Select a service
If your deployment has multiple services, select the one you want to connect to from the service dropdown.
Start typing
The terminal connects automatically. You'll see a shell prompt once the connection is established.
How Authentication Works
Shell connections are authenticated end-to-end using JWT tokens. The connection is proxied through the orchestrator to the provider node:
Browser → Orchestrator (JWT auth) → Provider (access_token auth) → Container
- Your browser opens a WebSocket to the orchestrator with your JWT token
- The orchestrator verifies your identity and deployment ownership
- The orchestrator forwards the connection to the provider using a secure access token
- The provider attaches to the running container and relays input/output
You don't need to manage any credentials -- the dashboard handles the full authentication chain automatically.
Terminal Features
Resize Support
The terminal automatically adjusts to your browser window size. When you resize the window or the panel, the remote terminal dimensions update to match, so output wraps correctly.
Reconnection
If the WebSocket connection drops (network interruption, provider restart), the terminal will attempt to reconnect automatically with exponential backoff. The terminal displays a message when the connection is lost and when it reconnects.
If reconnection fails due to an authentication error, retries stop and you'll see an error message. Refresh the page to establish a new session.
Buffer
The terminal keeps a scrollback buffer of 500 lines. Older output scrolls off the buffer to keep memory usage bounded.
Session Timeout
Shell sessions automatically close after 30 minutes of inactivity. If your session disconnects, just click into the terminal again to start a new one.
Not a Persistent Session
Shell sessions are ephemeral. If you disconnect, any running foreground process in that session will be terminated. Use tools like nohup or screen inside the container if you need processes to survive a disconnect.
Troubleshooting
| Issue | Solution |
|---|---|
| "Connection failed" | Verify the deployment is in a running state |
| "Authentication error" | Refresh the page to get a new JWT token |
| Terminal shows nothing | Try pressing Enter -- some containers don't print a prompt |
| Commands not found | The container may use a minimal base image (e.g., alpine needs apk add for extra tools) |