Shell

Work in a capsule on a terminal, or give a program a terminal.

Last updated 14 Nov 2026

On this page

Overview
Tasks
Open a shell in a capsule
Troubleshooting

Overview

A shell is a capsule whose main process is a shell program, run on a terminal with its input open. The program sees a real terminal: colors, prompts, full-screen programs, and Ctrl-C work.

You create the capsule with tty and stdin, and a shell program as cmd. Then you attach to it. The attach connects your terminal to the process.

The program starts when you attach, or after 60 seconds without an attach. The attach stays open while the program is idle.

The CLI passes the terminal type of your own terminal (TERM) to the capsule. The capsule uses xterm-256color when your terminal has none.

Item	Value
`cmd`	The shell program, for example `bash`, or any other program.
`tty`	True. The process runs on a terminal.
`stdin`	True. The input stays open so that you can attach.
Detach	Close the attach. The process keeps running.
End	The capsule ends when the shell exits, when you end it, or at its time limit.

A shell has no time limit of its own. It has the timeout_s of the capsule. The CLI needs a terminal on its standard input and output.

Tasks

Open a shell in a capsule

Reason for the task

Work in a capsule on a terminal, with prompts, vim, top, and Ctrl-C, or give a program a terminal.

Job set-up

Access: you.
References: POST /v1/capsules, GET /v1/capsules/{id}/attach.

NOTE

The CLI needs a terminal on its standard input and output. For a command without a terminal, see Commands.

NOTE

In the CLI, kode capsules run -it -- bash does steps 1 and 2 together: it creates the capsule and connects to it. While the capsule starts, the CLI shows a status line on the error output. Ctrl-C or SIGTERM during the start ends the capsule and prints interrupted; terminated with its id.

NOTE

The attach is a WebSocket. The SDKs have no attach method: attach raises an error in every language. Use the CLI, or open the route as a WebSocket yourself.

Procedure

Create the capsule with a shell as the command, a terminal, and an open input.

Python

sb = kl.capsules.create(cmd=["bash"], tty=True, stdin=True, timeout_s=1800)

TypeScript

const sb = await kl.capsules.create({ cmd: ["bash"], tty: true, stdin: true, timeoutS: 1800 });

sb, err := kl.Capsules.Create(kloudlite.CreateCapsule{Cmd: []string{"bash"}, Tty: true, Stdin: true, Timeout: 1800 * time.Second})if err != nil {    log.Fatal(err)}

Ruby

sb = kl.capsules.create(cmd: ["bash"], tty: true, stdin: true, timeout_s: 1800)

Java

var sb = kl.capsules().create(new Kloudlite.CreateCapsule().cmd(List.of("bash")).tty(true).stdin(true).timeout(Duration.ofSeconds(1800)));

CLI

kode capsules create -it --timeout-s 1800 -- bash

Connect to the shell with the CLI, which waits until the capsule is running.
CLI
```
kode capsules attach cap-3c4d5e6f7a8b9c0d
```
Type a command and read the output. End the input with exit.
CLI
```
echo $((6 * 7)); exit
```

Wait for the shell to exit. The SDK call returns the exit code.

Python

print(sb.wait())

TypeScript

console.log(await sb.wait());

code, err := sb.Wait(0)if err != nil {    log.Fatal(err)}fmt.Println(code)

Ruby

puts sb.wait

Java

System.out.println(sb.waitFor());

CLI

echo $?

Close-out

Make sure that the output shows 42 and the exit code is 0.

The CLI sends the new size of your window by itself.

To leave a shell running, close the attach and do not type exit. Attach again with the id of the capsule. To run a program other than a shell, give it as cmd.

Troubleshooting

Symptom	Possible cause	Corrective action
`409` from the attach route, for `stdin`	The capsule was created without `stdin`.	Create a new capsule with `stdin` set.
`409` with `has terminated`	The shell exited, or the capsule ended.	Create a new capsule. Read the output with `logs`.
`426` from the attach route	The request is not a WebSocket upgrade.	Use the CLI, or open the route as a WebSocket.
`404` with `not found`	The capsule does not exist, or is not yours.	Check the id in the run records.
The shell ends when you leave	The shell program exited.	Close the attach. Do not type `exit`.