Sessions & networking

Sessions let you run interactive commands and reconnect to them. Use port proxying to connect to a service listening inside a wisp.

Interactive sessions

Go provides w.Command("sh") and w.Exec. Python provides w.exec(["sh"], tty=True), and TypeScript provides w.exec(["sh"], { tty: true }).

With the CLI:

wisp console WORKSPACE

Press Ctrl+\ to detach and keep the session. Reconnect with wisp sessions attach.

Background work

Create an exec session with detachable enabled, then save its session ID. List sessions and attach later to receive recent output followed by live output.

An explicitly held detached session keeps an on-demand wisp awake. Simply closing a connection does not provide that hold. Kill the session or release its hold when finished. An ephemeral wisp’s maximum lifetime still applies.

Connect to a port

Go’s w.DialPort(ctx, 8080) returns a net.Conn to a port inside the wisp. The HTTP API exposes GET /v1/wisps/{name}/proxy/{port} as a WebSocket carrying raw TCP bytes.

This connection is authenticated. Opening a port does not create a public URL.

WebSocket format

Use wss:// and the same team bearer token. Exec and attach binary messages start with a type byte: 0 stdin, 1 stdout, 2 stderr, 3 exit, and 4 stdin EOF. The exit payload is a big-endian int32.

Text messages carry JSON control events. The first server event is session_info. Clients may send resize and signal events. Proxy messages contain only raw TCP bytes. Prefer an SDK to handle framing.