> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gmicloud.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Interactive shell

> Open an interactive terminal session in a sandbox.

The shell is an interactive terminal over WebSocket. Use it for interactive work. When you need clean output and an exit code, use [`execute`](https://docs.gmicloud.ai/agentbox-sdk/commands-and-files) instead.

## Open a shell

```python Python theme={null}
import json

conn = sandbox.shell()
print(conn.recv())  # {"type":"status","message":"connected"}

conn.send(json.dumps({"type": "resize", "cols": 120, "rows": 32}))
conn.send(json.dumps({"type": "stdin", "data": "cd /tmp && pwd\n"}))
while True:
    msg = json.loads(conn.recv())
    if msg["type"] == "stdout":
        print(msg["data"], end="")
        break

conn.close()  # close the connection; do not run `exit`
```

```go Go theme={null}
conn, err := sandbox.Shell(ctx)
if err != nil {
	return err
}
defer conn.Close() // close the connection; do not run `exit`

// The first message is {"type":"status","message":"connected"}.
msg, err := agentbox.RecvShellMessage(conn)

err = agentbox.ResizeShell(conn, 120, 32)                // terminal size, optional
err = agentbox.SendShellInput(conn, "cd /tmp && pwd\n")  // end a command with a newline
for {
	msg, err = agentbox.RecvShellMessage(conn)
	if err != nil {
		return err
	}
	if msg.Type == "stdout" {
		fmt.Print(msg.Data)
		break
	}
}
```

In Python, `shell()` returns a `websocket-client` connection. Send and receive the JSON messages below as text. In Go, use the `SendShellInput`, `ResizeShell` and `RecvShellMessage` helpers.

## Messages

Every message is a JSON text frame.

| Direction | Message | Meaning |
| - | - | - |
| Sandbox → client | `{"type":"status","message":"connected"}` | Connected. Always the first message. |
| Client → sandbox | `{"type":"stdin","data":"..."}` | Terminal input. End a command with `\n`. |
| Client → sandbox | `{"type":"resize","cols":120,"rows":32}` | Set the terminal size. |
| Sandbox → client | `{"type":"stdout","data":"..."}` | Terminal output. |
| Sandbox → client | `{"type":"error","message":"..."}` | This connection cannot be used, for example because another shell is already attached. |
| Sandbox → client | `{"type":"status","message":"closed"}` | The shell session ended. The connection closes next. |

Send only the two client message types above. The sandbox ignores raw text, binary frames and other types.

## Session behavior

* The shell runs bash as `root`, with `HOME=/root`.
* Output is raw terminal output. It includes the echo of your input, `\r\n` line endings and control characters, and stderr is merged into stdout.
* One command's output can arrive in several `stdout` messages. Keep reading until you see the prompt, or set a read timeout.
* Disconnecting and reconnecting returns you to the same session. The working directory and exported variables are kept.
* Only one connection can be attached at a time. A second connection receives `connected`, then an `error` message, and no output. The first connection is not affected.

> [!WARNING]
>
> Close the connection when you are done. Do not run `exit`: it ends the session, and every later shell connection to that sandbox receives `connected` and then `closed` straight away.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.